?cr Tae ATFLS lie smC lie 

-OS:-- 



'MI is MEET FEO&&LE 

PARI 2 s PIOML ISSE^'S SCJXDS 

PART 4 s PR0MAL LIBRARY 



SYST^S M«If JkSSGCiATiS. ZKC* 
3325 Executive Drive 
Raleigh, Hcrth Carcliua 27609 
(919) 878-3600 

Re^o C - Ssptaefeer 1986 



ii 



mmmtmmEmmB 



The PI/*: .A: ^-r. ± <Hge, Cot;,: 11 ^ , 'Sxec":-i'-.- 5 

and LiLHGij wcxc designed and written by; 

Bruce D* Carbrey 

The PROMAL Editor and portions of the /upls L1~/-Ij and 

Commodore 64 1 _ lcl~y .:>-;a were written by: 

^£ry Isaacs 

with programming cssis :ance from 
David Long 



Copyrignc - 1} 1^6^ 1SS5 : ^5?a6 Systems Management Associates, Inc. 

(Programs £ flan; sis. * All rights reserved worldwide. 



PROMAL and DYNODISK are tracemarks of Systems Management Associates , inc. 

Apple 11 arid rroDOS are trademarks of Apple Computer, inc. 
Commodore 64 is a trademark of Commodore Business Machines, Inc. 
Thunder clock is a trademark cf Thur.Jsr~csre Inc. 
IBM is a trademark of Interna ticnal Business Machines. 

RAMWORKS is a trademark of Applied Engineering. 
1541 Flash is s trademark of Skyles Electric Works • 



DISCLAIMER 

Systems Management Associates, Inc. makes no claims or warranties wizh 
respect to the contents of this publication or che product it describes 2 beyond 
the limited warranty which accompanies this product- The right Is reserved to 
make any changes to this publication or the product it describes without 
obligation to notify any person of such revision or changes* 



iii 

TABLE 



- ' ... \ JC, L 1 19' Z, "~ i- ; lL £~ ~ 1 - - - - e c s - 3 « - ^ - * - ^ - " - ' ~ <- - - = - _ ~ = _ ~ 

LCct-C ~ti§, •rr.t J '„T„™:£ - • • -.-.a-,;--.. ^ c - „ , . e » - - - - - ' - " •• 

Usir l5 lUtl-l Ine-^i ;~ - . - - * = = - = . : = - . ; -/ 

^Jriticg a ?~ og^s-a -nxh tns IdiuG:: <> . „ , . . : - . = , c , ^ . . . c : ... * - - - e 1-5 
Compiling four first rrcgranu 6 c c . - c c - c e c ^ c - = „ - c - c •> c - ^ 5 ~ c c * - - - r _=^1 

Executing ; 7 cur Frogrsxc ; ; ; : e , 6 - c e ^ - • • - - ~ • - - - - • 1-12 

Where does PROMAL pu ';. :U ?::cgr^::l c , e o e — s o ~ o £ = * c , = - <• = c * c * . c „ 1-12 
Revising your Pr :. , . , = - . - - ■ - - — - - - - - 

A Sample PROMAL Iszt -processing Program '^IifC;. . . - < . . . s = , -1-15 
leal {floating point: I J ^nbor = ^t~\\* i-3in^£ ?r:g/^n . l-l- 

An Advanced Program ; . CALC X * e o o « * * < . ^ « - c . = - ^ t o c . * * c - , , o c „ ~ c 
Advanced Editor il-^tnra^ . e c = * * . . « . » - > . o - . - * c - = - » * => - * — ■ 1-25 
Some Special CapEbi J irle^a • c , » * - * - c c < „ o * - , 3 c , . . — « c . t _-29 

A Database Application Program J -ipols 11; . c - s < = - = = c c * ~ ■ < ^ 1-30 
Sprites, Animation & Sound Synchesisr * Irs-ieccr e i*- c , «- a . = * c ^ c * - « 1-30 

in Conclusion* • • . . • o - c e c - = : . = c c - - * - - - ■- ■> <■ ~ ~ _~\2 2 

Developer's Version, Source Coca, £ Graphics Tooltcxc * * t „ „ 3 „ , c . e 1=33 
Customer Service. • . , ;: , c o e c 3 * 5 3 e , ^ o o - „ - . . c c, ^ 3 c c o o „ -3 4 



PAET 2 1 PKOSfAL USER'S GUIDE 



Introduction. . . . . • 2-2 

Manuals & System Startup o o * a « « o 3 o « o c * c * * <> o o o . = a a , « c c c c , e * e <, 2-3 

Executive Commands and Command Editing o a ; G * * e a o o 3 « « e . o c o o „ G o G e 3 = c 2-4 
Built-in Executive Z^n^arAs « e c « e c , , , , c , : , . , . r . c „ , c . . c „ « . c o . . .2-8 
Arguments for Executive Coiaesrils c , o = c — . ^ s a o c ^ « o s , o P = , * e o , = 
File Names • . • • o a « c . * . o « c <» c * e G - . * 6 s . , . o - . - ^ ~ c , a c c = c c c c c = c o s - c o 2-5 
File Name Extensions « « r . . e s o . e ; . - c . « . c „ „ . , « e c = c , , c e c . , c , * = . c 2-12 
Numeric Arguments - a = = = c = c , - , , , - c . c c . £ . . . , . . a « = . c , . = o ^ . . - . 2-12 
Device Names • « 9 • « e « . e o « « a « e & c c c * e e ^ o 3 « « 6 o e c c e = e 3 & « * o e a o « c e « e « « o e e 2-13 
1/0 Redirection^ 9 o . o , 6 9 G 6 c o 2-14 
PROMAL Executive Ccmssnd Su-Timary -cooler c , c , , , : , o c , , □ ^ . - 0,00 2-1^ 
BUFFERS (Apple 11 only) . , c c * o , « * . o c c c c ^ c . > o o o , 3 * . = , . o e o , , a ,2-15 

COLOR- . , , - , o , , , S S , c , S , , . e , , e e e e o * = e e e , , e , . , o o . , , o . . Q . . , . ,2»15 

COPY (EXTCCPY % . . , , c o , c c , o c c . e w . o , c c e c c , e , c , o , S c . a c * . o , c • . a c , 2~l7 

CS.. ..... 5 cocc..o...^.e.o... c.o. ...o.o...... .......... 000.02-19 

DATE • . c, _ = , o , S o , . o e o o e , o , c o . o o . o . o e . . c e o o 3 . . c , e . o o e o C a 9 o .2"20 

DELETE c , o o . o o o o . . o o o , o c o , o o o o c- c o o e e o , c C c c , o o o o . c o c . , e o = c C « o 2 ^2 

DISKCMD (Ccmmodore 64 only) e , * , o c c , o * * c * * * , * c , * c a s c £ . » s * e o .2-21 

3YNG (Conaodore 54 onl>) o , £ . e . c . . c c c c o - , c ; c . « o c e , . , c - c o o , ^2-22 

DUMP* . fc o c . . . o . . o . - . o . c. . * o . . . . o o . . . - a o , , o . . , . c o . . . . . , o o o . c o2^23 

EDIT . . . . . . .... o ..... o ............ o .. o . o .. c. .. o . ....... . o ... o . 2-24 

FILES (EXTDIR) e o o . . o a o e e . . a , c. . G . c . . a . o e . . . o c . . £ e . . o c , o . . 2-24 
FILL. .......... . . . .. . o . . ... o ......... . ..................... . c2-26 

FKEY. . . . . . C _ o o o o o . . . , o e o o o o e . e o . . . 9 o . . . o . , , c . c . C C . . . o o . c . 2^26 

GET. . o o c .... o c . 9 . o .... o . o c o c , o o ... o o o . c S o o . » o o e 3 o c ... e . e . e e . . 2 ""2 7 

GO. ........... c o ..... o ... o . o ................... o » .... e o .... c . 2-28 



5 c - . - - ~ . ~ c - - . - - , , - . 1 — - S 

r L'Lti o s - c - - r - - - .- w e - f , , - c - - o •: ' - - - c : • € c c c . ~ . <. c e o - a o £ ""-> 

A. J, ju'jui <- c e .j e c 3 c .i r o - c c e s e c - v. - ^ : e & o o - 2 - ' ->i- > cc»<~;,«>e'£*ce®~£>»ce©©e < £. X 

UNLOAD : . ; . c <, c . : , , , ... , : - , , , , . , , ; , , ^ r . v , : , .... 5 . * , 2-42 

CCTLOCK ;kppls 11 01117) 3 c . e - 3 * . - , ^ c „ t c - c = . c . c „ „ - . c „ t s c , c . . 2-42 

7 * f . ^ c . . . - - c . s - , . _ . . , _ _ _ c , v^A 3 

The PROMAL iter c . - ... £ c , : . , - e c , _ = . 

Display Screen fcr Ne T « r File, „ . « c « c . s e c ^ s - c 3 „ G « « « c o ^ 6 c o . „ c 2-45 

J 4 *- -S r ~. "7 — ^ 9 _ /, t 

-sUXUi ^Ojf Cscaojo&aooooojcosooooocccoo - cocoj-oosec - ©©ocelot o r Z, """" -.- S 

Ins ere ring and Deleting Lines • « . . t e « . * ^ « o . . c . o , , a * « e . . * . * « 2-49 
Searching with the PI HIT Key « , 5 . . 3 c . , = , * * . « . - * . c , . * , r * <, * => . 2-SC 
Search and Replace o „ „ e c * * <■ . « •> «. , . , , , . , , . . e c r 2-5 1 

Oit and Paste Operations ~ « 5 * « c „ s , c c „ <, c « „ „ . . - ^ 6 e o & 6 o c c o e c 2-52 
Saving a Block co a File o = ^ * c = c c e c o G c * o c o e o « <> « o , . «, , c c . c o o * 3 2-52 
Exiting tae Editor. ~ . , . . . r . c * . . r . . . « . . . . . . * . - , . * c 3 . „ . . . e . « .2-53 

Technical Notes an the Editor (C-&<i cily)ae eoee oaoo e9 , 9 o 0u ,, 2-47 

The ?R0MAL Compiler ... c c ....... * ... o .... c - c . c . * * c 2-56 

Command line Arguments and Options . « * . c . o . . * 3 e * . . o o « . c „ . o 8 2-56 
Dialogue of the Compilation Process <, * . e . c . . e * c 3 c * * c s „ <> . . 6 . * <, 2-58 
Differences between Demo and Full Compiler . o a c . . . o . 6 . . . . . c « « 2-=60 
?R0rlAL Crcse-Rsf erence Map Util it y (XREF) „oo - o 2-50 

WmMS 35 PEOMAL UMmmE MiMJML 

Chapter 1 § 1st rocket i^a e c e 9 c c 6 e e „ . 6 ; c « c , ^ e ; c y c c , c „ c 9 3 3 r s c ; , c « c . , o 3-2 
Chapter 2i PEOMAL Frogras^iag Language Overview. . e . t ........ .... . 3-3 

Chapter 3s Elements of the PRCMAJL Language. « « • « e 6 • 3 , e a o e . o e . e e 3-7 

Vocabulary and Names e . * e . . c . . . . . o . . . . e . . * « . , . *. . . . . * c o « = * . . . * « 3-7 
Data Types . . . . • . . . . • . . . . . . . . . . . . . 8 . , . . c . • . . . . o . „ • • o . . • • 3-8 

Literal Numbers 3 Characters , and Strings * o c e <> G c * o o « c * c o * * , o 3-9 
Variables- . * . . * * * * * * » » o > s c i * * « a c a c * „ * , . c . , » * c , > , , . . * ,o o .3-12 
Constant Definition. o * * * * * * * * * , * > G o „ * * Q „ v 9 s * e c * s , c 3-13 
Array Variables. * * * o « e o o o o e . * , c o . * c * « e G * * 8 c 8 * * a . a * c * .3-14 
DATA Def initiono . , e c c c c a c c c c c o . e , c . , o o c 8 o , a c o o c c , , c . .3-15 
Operators and Arithmetic Expressions * « « « « o « « e e « « « e « « . « a « e « o e c 3-17 
Relational Operators c » o e c s o o . o e 9 s « e & . * « c o « c « . » « 6 « , . e o « a . e 3-21 
Logical Operators* o * • . e , . o * c * c o o e c o , <> e <> * . o . * a * £ * e o3-2i 
Shift Operators. . a « • e « . e e « . , . • « e . 9 , « « e e « . . , . Q . « e « « e a « c o « • a . e 3-22 
Indirect and Address Operators « , . . , • e « e « « • . e e « • • e e c e « • a » e • e ,3^22 
Global Variables • . , o • • e e s • . s • . ^ . . e a . . e . e o o d e e • . e e . o . • 3-24 
Chapter 4j Statements « o a . . . . • „ ...... « ........ • . • . . a a . . . . . . . • « . . . 3-25 

Introduction. • . « . . • . . , . a • e » e 9 e e • « e • a 8 . . a e • • e @ • . . e « e . . e a 6 o , .3-25 
PROGRAM Statement (& OVERLAY Statement) . ... c ....... <> ....... . o3-25 

Assignment Statement * o a o o c « a o , o 3 . a e o <> G o . . o o * , . e . e o « . 3-26 



PZ'-ZZ . • , - = . c . e . , , , . _ t . _ _ , , : .-3, 

luil^-in Procedures and 7n::i^? - . _ . „ r ^ . . , , c . , ^ - — b-oc 

Simnle G^tpct ~ Fans c ted I^jraeris "itp^U^.^roe^^,. c - , > » c c - 3-37 

31 triple InpUt «, a s e o „ c o - o c o - - - 5 a r - c z r -o.co-cs-csc.-eo.cc-eo,,*.* 3~ 38 

liutnerlc Input o . c c „ o c c « . c «- . . ~ . r . * - , c > _ ? * * - . c . - * - = , , , : - = s 3-59 
User-Defined Subroutines . * * „ c .„ e . c c e <> ~ . * * o - * . • o * c o - . - „ «, * , , . 3=41 

rassec? Arguments : - ........... . c - r c . .. . . 3—42 

Local Variables-- ~ - — — . - - . , „ - =. . .3-45 

OWN variati es^-^-o, . - , e - - - - . . . ^ ? - ^ ^ c - ^ , ,2-46 

Good Prog ramniiag Practices witri Subroutines < * * , * . - . , . . c «. o - .3-46 

-_lS CulSiOT.o o o u r c s, s . „ oooa^e^ sef-o-eet©-; ._> c o o o © _ o c o . • e o c c r- ■ oorae^j / 

INCLUDE Statement for Multiple Source liieso „ , . ~ . c - * . c3~4 8 

LIST Statement for Selective Lie ting o . . e c . = c , c - . . * . , . - e 3-48 
Condi clonal Compilation* . « ^ * - , c c . . . o = . , . . . 3 e c c . . , c * ~ . = . = 3-49 
Chapter isterf aclsgc c .- , c , ? c . : « a o c - c a e o <= - * o c c „. . . . = « « c <> c . . 3 . 3-51 
Opening and Closing Files and Devices - •« <> , . r * * « « c « c o ... . . . o * 3-51 
Functions for File and Devi 

STDIN and STDOUT File Handles c ........ t ......... c .„ « 3-53 

Outpuc to Printer, Control and ESCape Sequences. . . c „ , * . . e . . . 3-54 

Argument Passing from the Executive. , e e o G « « o 9 « e e * « , , e e « o e . e 3-56 

EXTernal Variables for Special Memory Locationsoc ...,,3-57 

PROMAL Interface to Machine Language* . .... e r ..... o . « 3-60 

Chapter 7i Strings sad 4rrays lewisiteou o e c c e . c 3 « a « « « c , . . . e e o c o « 3-=6i 
S t rings c c - : 3 z « = ; . s .- 1 , a . s . G c » c « 3 e « o * c » * * c 6 . , c a r e * ^oo 6t9l .-»3-61 
Address vsrsas Content of an Array Element « , « « = c - , « , o « ^ c , . 3-62 
Multidimensional Arrays & Arrays of Strings « => c . e • s o « * c a , c « o . c 3-64 
Presetting Global Variables e « . . . c « „ = <, « « . * . e c £ c . & c , = a u c 3 e a 3-66 

Cbapter 8§ The Loader. . . e c ^ 3 c 6 - . = - c - - . - . . . - . 3 c 3 c c « * . . . . s e - . 3-67 

Definitions - . . . . . „ . . . . « . . . . . . . . o e c o . e 9 . . e «, . ...... . « . . . „ . , .3-67 

Modules & How the Loader Worfcs * * e = * * e c c = c _ o o , c , * e , » e « c o o e e 3-68 
Calling the Loader and Options . « c . . , o c c , . o o o t « c c o . , c , o c c o 3-70 
Exporting § Importing ¥ariables and Subroucines. c .... e .... . . .3-73 

Executing the Logical Program with Separate Modules. . o o..... .3-75 

Using a Bootstrap to Control Loadingo . . e . . . . . . . . . . . . . . . . a . e e 3-76 

Using Overlays <> o e , c * Q « e e « o * e o e e « e e * o o » » « « e e , 3-77 

Considerations for the Executive and Editor . . . .. . .. . . .... a . . .3-79 

Successful Use of Overlays § Separate Compilation^ . . a . . . . « . . . 3-81 

fait 4 s mmm, libeaey mmual 

Summary of Library Routines . • e « * e « 9 « • o « o e , « e • * . o e e « e Q « e * « « , • e 6 4-2 
How to use the Library Routine Descriptions « * • • 9 • . « . e « . e e . « e » » @ « @ 4-4 
PROC ABORT , FUNC ABS , o 9 . . 9 . o e . o . .... e 9 ... e G 9 ... 9 c . o o . o . e 4-5 

FUNC ALPHA, PROC BLKMOV. . . o . . . e o . . . , . . . , e . . ....... o . .4-6 

FUNC CHKSUM, PROC CLOSE. . .... e o . 5 ..... o ... c ...... 9 ...... 8 . . .4-7 

FUNC CMPSTR. . . . . ...... . . . . . . ........ . . . . a . , s « e . ....... . . . . . . . . . -4-8 

FUNC CURC0L 5 FUNC CURLINE. . .......... .... e . s .......... s ...... e .4-9 

PROC CURSET, FUNC DIR. . ... o .... ............. e ...... ......... o . . .4-10 



TA. ' CONTENTS 



7 v* 22:^:77^- . - - - - . , = ~. 

777: zzzzu'i . , . c . : : 

in: 222^ - , ^ -. = <-., . _ s c , , - - , = s . , . - - _ 

- ^ - ; T7"F~ - • , , . ... - c , t .. .. , _ . . • - G- 

_ . — ^ ^ ^ ^ ^ * 7 I 

r " . " i, . , . c a j - , - , . ~ - o - . . - « , - - - c _ =■ * '- ~ .*=, 

ElZtZ G£2FCfF /.:r:r II : . * - - * - - • : - 2 • 

5'Jl'IC G12TST; riJ-JC 9,1 X ''il^w - 5 5 - - - C - " * - t - -, - 4 - - e - r - 5 - ~ 1 ' t - 9 - C ^ .4 « 

f UNO INLINE ; I UNC 12LIS1, . . . . . * . . . * . c * . . c . . . . c = « * c . e ^25 

r'JNC INSET e = , e c o , c ^ . - - o * = - - * , . * : . * o ~ ' - o - -- - - o - ' e c . 3 , 7 7 

7 EGG I:JIS T a. o c . c , . c C c 3 c . o = c c • ~2 C- 

PRO r ' SF : 2 7>'G 1 - Z'SZZ^ - „ _ _ _ ,. „ . , , : : ^-.:ZZ 

PROC L-AD, FUNG L0GX8TR 9 c , , . « - = _ . , r - , 4-30 

FUNG Milll . • , - - ^ e , = c ^ - - - - - ^ ^ ... = = . o 3 ^~2 1 

FUNG Mliv y FUNG KLGE? , . ^ , „ . . , o - c ^ _ c ~ , e . = c c c , , c 9 t « a , . , . e • - . , t ^ -32 

Z 2G: : liCGSGG. . . . - , . , „ - ^ . c e « c = ^ e . . 3 ^ - = - - . c . 4 -2 3 

: r 'UMC HUIGEEIC - . c. , , _ c . o c c , - , t o e . : c ^ c ,^ o c c . e , c . . - 4-24 

FUIC ;^pg^s 72 Gnl;% . t - ^ _ , , , t . . c s . e c - & , * ^ o4-=35 

FJHC OP£i>c .coco , c , 5 ■ ^ c c , ^ - . - _ c .. _ „ c , s ; c _ _ _ . , c ^-36 

?RCC OUTPUT c ~ < . , . . f , o ^ , = - , - . - , - . r o , c o ^ c o = - - - c , c c = 3 , o c r - . . , 4 «4 1 

PROG OUTPUTF , a c . « • . r c . , . • c c . e ; = , . « - , - » • e , - « , « c e c « o c e ^ c r - e o c o e . . 4 -43 
PROG FROQUITj PROG ?G T 2% c . o e , c « . e e o - - c = , . « 3 . ^ . ^ e o c o , . - * e . c c . • , 4-4 4 
PROC PQTBLKF e « - , 5 , . 5 c 3 » e = e . « . c « 9 e « - o e c 3 . c c c e - o - ^=-45 

PROC ?UTF S FUNG RANDOM© o . . „ c 3 . - , , ^ ^ e ^ o c . , = ^ * , - • c , • o a * e c c • ^ , o e 4»4 7 

PROC REALSTRo o • . . v » c , o r o 5 - . . o « o c c e o • e c o . c c o . c c * c • . c c o . = r c o o 3 « , e * 4^ s S 

PROC REDIRECT, o o c c 3 . o a = e c , c . ^ „ o o o , o e c c c o c o c c . o , c c o - , e ^ . ^4-49 

FUNG RENAME o o <, o , « o c ^ o o c ; o c o e e , c e c 3 o , c o c o , c , o . o , , e . c o , c a « . c c c 4-50 

PROG SETPOSF (Apple II cnl y) c , • , . - , , c e . c - . o - e . c „ . - ■ « ^ , c - e ^ 4-51 

FUMG SSTPRSFIX (Apple 11 cnl;;^ ; F"£ J C SGRFEAle . =- „ = 9 a ^-5 2 

FUMC STRVA1. o . c o .... c o _ c , o c . c s ; 4-53 

FUNG SUSSTR; ?"JNC TSSTKFYo , c . , ^ c ^ c , a c ^ £ e o c c o , c £ a c c - c . = c ^ a ^ c 4-55 

FUNG T0UPPE1 o o o ,o c e a o o e ^, , - o o S , = c e . . o a o , . . o . . . , e . o o . « . . . c c . o 4^=56 

PROC WORDSTR, FUNC ZAPFILR ~ ^ , ^ - ^ - c c , c - ~ c e , = , , 4-57 

ilPFEMBICES 

APPENDIX As ASCII CHARACTER SET* , o , a , , e o . , o e , o o o e s 3 c , , . e . o , , , , c cA-1 
APPENDIX PROMAL KEY CODES RETURNED BY FUNGS GSTKEY AMD TESTKEY, . oB-1 
APPENDIX C § ERROR MESSAGES a MEANINGS * c o - o * * o c e <, c • o • C-l 

APPENDIX Ds LOCATING RUNTIME ERRORS § VARIABLES IN MEMORY, . . a . . • . . . . .D-l 

APPENDIX Es PRINTER SUPPORT c , c . c o s , o o o . , , o o c c c o c c e , c c = « , c e o a = ^ ,E-1 
APPENDIX F s DATA COMMUNICATIONS SUPPORT . o .... e e « ... o o .... F-i 

APPENDIX Gi PROMAL MEMORY MAPS . . . . . . . . . . . c • . . «. . . « s . . . . , . c . . o . . . . . . . G-l 

APPENDIX Hs DYNAMIC MEMORY ALLOCATION* o . c c. c ... * . e o . .H-l 
APPENDIX I ^ MACHINE LANGUAGE INTERFACING. c . 6 . . . . . . . . . o . . . . . a . . c . . c a o . I-I 

APPENDIX J t RECURSION AND FORWARD REFERENCES. * e e * * o . c <, e . * 9 * . o c « * e , * .J-I 
APPENDIX Ks REAL FUNCTION SUPPORT » . . ...... . . . . . * . . . . . . . . . . . . .K-l 

APPENDIX Ls COMPATIBILITY ISSUES • . . . . . . . . . . . . . . . . . . . . cL-1 

APPENDIX Ms COMMODORE 64 RELATIVE FILE SUPPORT a ..................... .M-l 

APPENDIX Ni OPERATING SYSTEM NOTES. . ........ .... e e ...... . o o ... e . . . „N-1 

APPENDIX 2 BACKING UP & FORMATTING DISKETTES. . . . . . . . . ... . . . ....... . *0-I 

APPENDIX P: SYNTAX DIAGRAMS FOR THE PROMAL LANGUAGE • • . e ..... e .... a . . eP-I 

APPENDIX Qs PROMAL DEMO PROGRAMS. . s . o . . a . o , o . - , . . e . c . . . o . . o a c . . . . a . .Q-l 



AL„1: -l 7 j - : - : • . * 

r,i?xl 1 I \. - - - ; 1 * / 1 1 i ,1 2 " / ' " 

^ ^££:u.c:-.-- o - - - 
• ;u:ac::';::-:: i". "j! "711= — - - ~ ~ 1 1 
j zi'jze tic -xpr = i r ic » e - * - - - o . ^ 3 - 1 7 / 21 

rtrlch^etic operators - - , - a . c c — ; r = - 3-1 1 

Arrays s 

— of DATA strings e c = - - = .-i-27 ; 3-13/ 16 

™ declaring, t ,..c (9 '; e <, l5 c*«.;-li- 15 

— mu 1 1 1 -d iraen s i cna 1 3 3 G » t 3 .3-15e 3-6 ^ 

ASCII character set . „ 3 . e * „ . , * „ • , . „ . A-l 
ASM routine s declaring c . 1-7/ 10 c 1-12/ 11 
Assesiblj ls.:iguage subrc^tinas § 

— calling 113 routines frcsc - . . -I-IC 

— interfacing to. » * <> «, * <> c 3 o , c « 1-1/ 15 

— relocatable* « « o o = o . e c « & s o c 6 1-11/15 
Assignment statement c * 8 c * » c o , 1-19 5 3-25 
AT keyword in EXT statement . * i-29,3-:>& 

ATAI (FUNC) COOOCGC 3COCOOoGO<" O^CCOO O K~ 1 

Audience . for FRGhAL c * c = c o « a * « , o o * 1-3 

1 

Backing up disks a <. < „ « , c o * 3 ~ * — . ,0-1/-* 
Batch job capability o e o . e . o e . « ,2-30/31 
BEGIN statement , « ~ „ « o c «> * . „ e « . <> « .3-41 
BILLIARDS c. S (sample program) « . « o « G « C;-l 
Blank lines : as comments o 9 e , 9 e a e t »>lc 
BLKMCV (PROG) c a 9 o = _ = , , c = o 6 c , c . , . ,4-6 
BOOTSCRlPTe J file- . „ c , . c „ . , * . . . =. c o2-30 
Bootstrap, to control loading* o o = 3-7 S 
BREAK statement . o . o e « . e e e , 6 « e * .3-31/32 
BUDGET eS (sample program) • . . . r 1-24, Q-l 
BUFFERS (APPLE II EXEC cmd) . . c . „ . . 2-15 
Built-in functions I procedures 3-35 
BYTE s data type. . . o . /. . . . • • o 1-18. 3-8/9 



CARG ?ar i ab le . • 1 -1 4 / 1 5 , 1 -2 1 / 2 2 , 3 -5 6 / 5 7 
CALC . S (sample program) . . 1-24/25, Q-l 
Characters , literal « « « G * * « e e , , @ « . « 3-10 
Characters, string extraction* .3-23 
Checksum . . . . . ..... . ... • . „ . . . •1-13,4-7 

Checksum, MAP display ...... . . . . . 1-13 

CHECKSUMS (sample program) . . = . . . . .Q-l 

CHKSUM (FUNC) / 8 .,o S900 . e9eo8 ., e . os W 



1 •- F- r,l- 



Ich lYd FP111AL 



:-~?c "wi"i T 2. -.7- 

— rotation c --nr ic::. o - 

— - El 111? 1.1111 11 c - - . 
Ccnnent 1 - r: e e o ~ e . - „ & = * 

COMPILE ^EAEC cr^d; o . 

" =, "~ c o uj-ixl a i 1 u. opcicriE « e » 

— cress reference 3t 

dIalOg . • . • ^ c e o . 3 c r 

— edit after errc:: o , 

— introduction to. o c 

— Invoking 

— screen displays ~ « - 
Compiling, conditional 

Compiling, sample program 
Compiling, very large prgrius 
CON statement 

Conditional compilation « * - o . 
Conditional stmts : short-cut 
Constants 5 defining o 
COPY (EXEC cmd) 
Copyright Notice 
COS (FUNC1- 
CS (EXEC cmc j 
CTRl, " (Adj. rt, -APPLE II). 
CTRL \ ^Cir. end -APPLE II) 
CTRL [ (S^srt of line 
CTRL A (Aiphalock) . » . . . . . o 1- 

CTRL B (Cmd recall) o.l- 

CTRL C (Abort cmd c -APPLE II 
CTRL D (Dei char . -APPLE II) . 

(Insert -APPLE II). . c 
(Strt of In -APPLE II 
( Indent ) c o = o ...... . 

rto -C64) 

end -C64) 




CTRL E 

CTRL F 
CTRL I 
CTRL J (Adj< 
CTRL K (Clr« 
CTRL L (End of In -APPLE II) 
CTRL N (Next page j . „ . . . . - c . e 

CTRL (Adjust left) 

CTRL P (Previous page)o 003 .. 
CTRL Q (Un-indent -APPLE II) 
CTRL RESET (Abort cmd. -APPLE 
CTRL STOP (Abort cmdc-C64) 



n:^--/£- , 
'- ' 

. e oL-1/2 

, o .2-55/ 53 

-:1 2-55/ 
=2-56/58 
2-^C 
. c .2-58/60 

o 2-5S 
c 2-5S 

c 1-11,2-56 

. e .3-49/50 

eooMl 

2- 57/58 
1-26,3-13 

3- 4 9/50 
o . o3-»33 

-26,3-13 
2-17/19 
oil, 1-2 
, = - oK-1 
2-19 
1-28,2-48 
.2-5,2-48 
- 2-6, 2-48 
9,2-6,2^.8 
9,2-6,2-49 
2-7 

o .2-5,2-47 
c ,2-5,2-47 
)o 2-6 ,2-48 
e o c a .2-48 
ol-28 5 2-48 
. .2-5,2-48 
. c 2-5, 2-48 
c c , c = =2-48 
ol-28,2-49 
oeco o,2"»48 
e .o. 9a 2-48 
II) 0O .2-6 
.......2-6 



Copyright {€) 1985 , SMA S Imc. 



INDEX 



: i r% — ( 



CTRL 2 (End of 

-'::l - c 
;uro_l ;p::kd . 



strings. 



— arrays oJ 
~ c-firi~g 

PJEaL = = * . . . 

5 : :?te:;cr.: e^r^la. .. - l~k" 
Lara zzrmzvn taazi ers svtp' r:^ 



1 ' r 



I's-e 



DiiTK ^EXEj end 



Delete xe T {APPLE 21} 
DELETE {EXEC cmd) ..Leo , 
Denjc uisfce;ce : limitations 
Deiuo programs 

Device names (TaBLE 4' - - . . 



» .2-20/21 
•••••• 1—3 

....Q-l/3 

~, .2-13 

lev-ire nrcber? ( ^ 2 <-/ - — - c . - c 1 ,E-1 
Elf 'FUNC; .c ...4 -10/11 

BIROPEN r FUNG ; c , . c c , o . s > . e „ e c , _ 4-1 1 
EISKCKi EXEC r' e - e t * - . i~2: /2/. 
Disk dri-e?- Y-? s^c^rl . f - - - , . !T-1 

DUMP -onLi.£.nd g example - = - c c S3 , 53? od-.5 

TUltP '^EXEC C!Z£) , o c . ; c ~ e o c = ~ _ * . - . 2-22 

DUMPFILE.S 'utility program - «. c - 
Dynamic metier y allocs tione . * , -> c « /H-i 

DYNO (EXEC CSCPco,: _~c.cee.-o 2-22/23 

DYN0D1SK o - ^ - _ l~5.2-?2/23,"-i5 



EDIT {EXEC c^d)c sec . . e 2-24. 2-4^ 

Miters .o S e.=.ec. , c , . . l-9,2-2,2-W55 

— CHANGE {?6) « . . „ . . . c ■ . . . ^ . 1 -2d. 2-51 

" COPY {F7i e c e _ . c c , o _ . . 8 e , < c c ♦ 2~52 

— char, sets & ^.edas ; = < ? , « 2-55 

— cut & pasta operations*. * * * , e e .2-52 

~ DEL LN (?!}. /. . e . . o 9 s e _ - c e , . e 2 *=4 9 

— display format* o o«.. o..«„. .2-44/46 

— EDIT (EXEC- cmd}.......*.. 2-24,2-44 

-- edit buffer & workspace e • . e2-54/55 

— editing Keys (TABLE* 5) « _ oc .2-47/49 



ng. 



1-1/ 



— QUIT display • . . 

— 111! ^ „ 

— pe o^ii ;ii; c - • . 



• ^^^^ ; 



seaicL 2 re^l^s . . . - . * * = c l=~2c j 2-51 

— sesrchir^gc , o c - , = . : s , , , , , c2-5C- ; 51 
™ status crae^ - : - , = - e = . =2-4€ 

— ;J?1TZ ,f 1; * ~ = . c s 2-52/53 
ZELlIf^ {-[ t fc; s , = c - c . r - - . c . = - -12 ; 1 1 
Error messages - ^ , c a . ~ 9 e , 5 = j-1/12 
Errors s 

~ from LCADer . « _ e , c e . , c , c <, « c 1 
~ sfzev OPEFo o , c c o , _ . - . 5 = 4-3- 
Eiiez~cz±Tig sample ^ r^graiL= ocs . c 1-12 
Esa^txti^rs s = = o o o - ^ = - , e , : . , ^ - , 2-2/42 

— c?rg;zosnts 5:r ccrrc cis c 2-r s 2-12 '13 
™ arg passing 5t. cmd line * c — 3-55/57 

- ccotan/s- search order « : ; - ,2-2 
™ commands, sucaerr (TABLE 2> sse .2-S 

— entering cc^tzE^iz - „ , e . _ _ . e . l-c/7 

— guided coar cfoo.o^^.e^ccI-S/? 
HELP screen- c ~ ~ = ^ - = . a , . , ~ > c c « 1-8 

— - line edicliig ke; s c , .. - . - , . . 2 --5/ 5 
user defined noa^an 5^ ^. o - - - , - .2 = 4 

EXIT (PRCC) , c . . e e a e c o c a £ o , s . . , o c , 4^1^ 
EXP (FUNC) c c c c e o c : £ , , , = , c c . c o , , . _K>" 1 

EXPORT Keyword *<> c . Q » Q 3-73 

EXPORT (cE) fIIe8,,^ e = eo c C000 3-74/75 
Exporting, defir„Iricn= , o = = : e . , *3-73/?~ 

~ arIth Q etICo , , c 5 , , e ^ e ^ c e 3-i7/ 20 
~ logical . o _ „ - c * ...... a ^ 3-21/22 

— mixed mods, c . 3 < c , , , ... * c * , c c c 2-18/20 
relational ... = .« * <-.<> c <, e * . „ 3-21 

EXT keyword c . .... c ..... . . .1-23, 3-57/55 

EXTC0PY (utility command) . . . . 6 * . . . 2-18 

EXTDIRs (utility command) o .... 1-7,2-25 

~ example of . . . . . . * . , . . . , . „ . . a , . 2-25 

Extensions 3 file name. e ....... . .2-12 



Copyright (C) 1986, SM. lie. 



— -:\ .r- ~ 1 - ; I 7 c ^ . c c . * - . . - ~ i - : ^ 

Files s 

— ;-cr.dl5. ci-:ir.itic.-. . -1-1". 3-r 

— ui - , . - . , c - -s; *?? 

-"-.rr^ -'ZdlEC 2/jL- r *" : , , - . 2~"-. 1 

fdldl {Ed^d cr-Li'c - - <■ c c- ,^11-/2;; 
FILL ^SdZl z~z . - - - - . 2- ll 

-ill • . c.^.c 

?1K2=5 .^e.^ 1- :::: ^:~/-d' • c , . -1: - - : 1 * 
FXEY ; EXEC ciid "• c . . ^ , ~ c - - * - ^ c 1 -2b * ^ 
? KEYSET 1PR0C],.- . — c o o . e - . --15 ; lc 

FKEfSET ;??XC; . 3. * . = . ~ — , o . ^-1- 
?1E scgteea^t - . . . • . . « - o , = 3 . = * c 3-2*/:^ 
E c- c s : r i rig . e v- T r aC s ^ e ^ o . ^ Z -3 / - 4 -~ ~ 
Ecr^att^d racpirt, . . - f ^d ; - . 
Forma cti:ig disks c s - « . » ^ ~ ~ c 1 

Zrr^rd ^fer^tic^s - ^ - - = . c . , - 6 c . = c ~-l 
FUI\C : func-I^n hsaoc, = c . 3 . * c2--*l 

3' ~lir- t d CI! "*v*»': ; r J? w 

" - ~ £ af i : : d^G - - 1 ~~ , - ^ : ^ / - 7 
~ editor's .:'is>cTcc. ^ - - — - 

- - ^ w . = * . . , . — ~ 

~ argumscts in - c . f » e c c c 3— ;£/ h 5 

~ ItltrC tCc e c c c « c e , a , - , s & c = ? e . - c^^^C 

— REALc - . o . c , , c c c ^ . - e & „ ^ . . '2 

G 

GST *HX5Cc3d>c. . , — --^2-2?l: 
GETARGS ^?U£lC^ ? - = c _ = = ^ c . = , , 4-1 . 
GSTE'IK? ..FUftC * - - - - c - « - - c = , = c . . 1 
GETC CFUriC) ^ ^ 

5ETGF ;?JIX'C) e c S . c c o „ , o c c , c , o . .c^-21 

GET KEY (FUKC: c c c c s = ^ - , c ^20/21 ; 3-1 - ^ 
G£TL (?5,0C> . ^ c - - - o c o , .4-21; 22 
GETLJ (?U1C) e * = « o c o , = c c c c . c « 4-22/23 
GETrCSF (FUNG) ^'??LE II* « . c « . . . o .4-23 



-5^dscii:£.I L5sd ifi 1HC ccc^.^.i-l. 

h :;iE > i-. - i^i ^ , - , , , . . . • - c * . = 



ill: 11 :^.i. . 

lllllcf x = 
l^c 

'..'v.- - _ ; 

„ 4 / " V 

..... ..,-0 1 X" 6 C C 0"^ O ^. CI. I-J-co.-sceis-' — — -' ' — ""* 

I"^II.I?;;1 ^£^rl= srogrE^"^ 
Irrlcialie5ti-;o_ ?EC:.^.L £rs:s2 
liilll^Z . EUF1) o . 
1ZL1SI tl*l T ~ T l~ - - 
Ir-p"j : ~ . iu.ns r 1 2 c 
Input, simple.. 

ii^sn :z:i\w; . , - 

1:3:1 K~> : "^ 



■ ^ ~ 



T MT ft at a 



•1- «: . £.:di- v- 



1 



3-39/ 41 

3-31/ 1 5 

- - f 7 
^ t • : 

3-51/60 
:-::!: 1: 

T — 1 S 

, . .4-28 



:zTSik ; i?n ; ^ — ^ 

IDERROR: 

— error code varic :1 - , . 1 ^-5-. ' A --r r 

— errors , cod-s? :::^-e-^-:--ci^G 

I:G? 

~ functions GEILF 9 ?ulZ- =,5-52 'f 3 
— • redirection- . . • - o o , o , , , , c o = c , 2-i-4 

— redirection, example of c « 1^-3 s k:-!^ 

— witb files STDI>V STrGUT - e 3-53 ^ r4 



?:3 ;iZSl ci5c* c - . , . . c c « .2-30. 31 f --33 

JOB files w> ^ , - c , ^ c . c:-:u';, 
~ substitution arguments ia.* c -*2-3l 
did. : P5.GC % . _ c . e . 9 c . - * . • . . o ;-29 ? l-l ; 



INDEX 



1135^.7* = . , • .: . . i 

•= = 3. - ---- s , , . . , ' .. - . 

- * ~ thus l * o ~ " y" dr.-.* , - ? c - , , - 

line editing re/s '1^311 1 /G « .1-5-^ 
LIST statement ^ - , .1-42 

Literals ? , o e e , . . . c o c - , , . , = e 3 . 3-S/ 12 

— cne::acte^ s = c c ... - ^ ? . . , . 3-10 
-lumbers - ■ - . . . . . . . . : ?-?/ 17 

C^llg^ , o - o , w c . . :. c c . o . o , r . c -i.G/ll 

LGAL (?P/-r. . ^ ..... , . s . , 3-70/73 , *-30 
L3^BIL; ^ o o . c o e e _ _ . . _ , _ c c c .2-67, 82 

— bootstrap program withe c ~ .3-~~/~ : ~ 
~~ :dling/ 9 /c^cc^. cs ^c. ,3-71/72 

— def ini ticns ^ad- . . * . - e • „ . .3-67/bS 

— errors £rc:z« - c . c - - * c o ~ ~ - c . . * s 3-71 

— EXPORTlng definitfcnsc . _ = ci-73/7^ 

— IMPORTing def ini rions c . . , . . 3-74/75 
-- memory diagram c 8 = o , & . 3 1 ,3-70,3-78 

— operation of . * . t . * . - . . . . „ . „ 3-68/ 70 
~ options for* 9 < « c , e « « « G c c « e e . 3=72 

-- overlays * - - c o e - ^ c e c . £ , c c c5^: 

— separate compilation.**^- 3-75/75 
Loading, PBOMAL diskette c e t o « c . 1-4/6 

Loading £ progress * o . - 3 . 2-21728, 4-32/33 
Local variables. .e. . - . , - -19,3-45 

LOCK lEZi: rsd; . . . . * > . , . „ , . \ . . 2-^2 

Locked fiIeoooo 9SJ , -c 2-?2,2-42 

LOG ( FUFC) . o c c c c. . „ , e . o , * . c a , o K~ 1 

LOGIC (FUkC; . e c , c t = . ..v-i 

Logical operators. c ~ _ e . e 5 . . c . o .3—21/22 
LOOKS TR (FUNC) s . ...... ... _ ^-30 

M 

M array o o a 3 o o c , , . . e c c c. <, c «,3-24 9 3-^4 
Machine laagimge ^rograsss 

— calling LIB routines fron.cd-iC 

— calling with JSRo , . , * , .4-29, 1-1/4 
~ embedded in DATA . « c . e c , . a e a 1-4/6 
™ effect of 3RK= o e « 3 3 , . . « . c • « a 1-3 
~ executing with GGe . e = : . . , e .2-28/29 

~ interfacing to 1-1/15 

— - interrupt service with *> * s ? ? e . ft 1-15 

— loading with GET. . . „ e . • . . * . 2-27/28 
~ loading with MLGET, .4-32/33 

— passing arguments to c c • 1-8/10 

— relocatable o „ , o e , , , . . „ * « .1-11/15 



".: - -~ i. *, ■ . . . _ , . . = _ - , , ^ , 
72211 . 7"U-**1. ^ t , , . _ e „ „ 

L-il" (F" ! I T ' ■ , - 
'-71 

"••-71 ^r<i :• - . yi\ 



7 --T-T" 



£ames . rr 2 es for s - : o: .-c3-?/8 

jJCAEG -ai : a b I £ , , . l-ll-l^ 3- 

1 7 E¥BIR (EXEC cmd 3 o o c , « c _ o _ , c , ^ 2-35 
NEXT s ci? t euier t = , - t ~ „ - , - c * ^ * 3-22 

NOPwEAL f.EXEC cmd? * * * o 9 „ c * . o c 2-36/37 
]^0T cper^tr:^ . , . 3-! " , 3- 21/22 

Negation. ccn T enrions c = ^ c o - . . . c . c .2-9 
NOTHING statsrrent o o , , e e c 9 « , e « . c & . 3-32 
Kui^ (!■; dsviee* ..coco ^ c ^2-^3^2- 
Numbers : literal a ...... a c . & ... G 3-972 

NUMERIC (FtMC) c o o o o c o c c o o . c c c . c o4-34 
Numeric input o o , c . = a o c e . 3 , c . o 3-39/41 



j % compiler optior c c , . c , « o . c c c * 2-56/5 7 
Object program o o . o c s , o o . , a o « o „ o c o e 1-4 
3NL1HE (FUNC) (APPLE H) _ _ , 3 s w . c ^-35 
OPErl friW . - . - ^1-^2^-51/55,^-25/^2 
C;PEi^ j error codes ^ ... c . ^-35 

Opening files - ^ s c c c o . e 3-51/52 s 4-36/40 
Operating system notes o « e c « e c , » cM-i/2 
Operators z 

arithmetic . . * f . o , , e * * , e c a , c c j-17/18 

— indirect & address . . ....... 3-22/23 

~ list of alL..-. we9 .3-17 

— logical = * c , . - c . * c e * e s , * o .3-21/22 

— relational o . * o e , , 9 . . , e c . 9 . , . c 3-2i 

™ SMft o _ o s = , c . c ; o c , c o * _ c . c o3-22 

Options for loader. . * * c 3 , e c * o 3 e o o .3-72 
OR operator, 00000,0*000 = 3-17 3 3-21/22 
Output s field descriptors. o o ..... .4-41 

OUTPUT i?R0C) « . e o o , . . s o o e c c o c o c 4-41/ 43 
OUTPUTF (PB-0C) . o o , . = . o c o = = . c 4-43/44 
Output s 

— formatted numeric. -3-37/38,4-41/44 
~ PROC, example. o c . . o . . » . . . , .3-37/36 

— simple e . . c o . e . . o o c e . . . o . » . . . 3-37 
OVERLAY statement o . c * c c c 3-25, 3-77/79 

Overlays s 

~ definition of - . . . . . . . . . . . . . . . 3-68 



Copyright 1986, SMJu lace 



INDEX 



3WH 



i - . _$n,b£ c . .L°~- 

P P.C df - J^"' : - ■ ... : r . • ; , = " - e ^ , 

P~im r :n « - - • - e - c ~ . — - .: ' • ^ 
— - - — — f - - y 

.PREFIX ..LZE2 u~d,. - . . - . -2--l„L- 
Printer (?'' r-evicsu . * - . . 2 -13\ 2-54/55 
Printer support*, « c e 3 c , . e c <, £ = . o oE-1/2 
PEOCe -procedure header. . o . ,3-41 
5roced%sres fe fractions: * c . I-18 ? S-36/47 

— passing arguments tCo 6 o - * c 3-42/45 

— iocsl variables it ... c ,3-^5/4 6 
ProBOS . special functions ^ , « c c , « , e ,E-2 
Program authors c c ^ = s c o s , e ^ o ^ o di 
PROGRAK s^atesant . o o . = * . c . , = c 3-4 % —22 
Programs, desss ^ - - ^ * - . - « . . c . s - 0-1 *3 

~ BUDGET e c o . . e t o c c = e e c o . o = = c , , . = i <=*2 4 
« CALC e * e c. o o c :> o . - , o * e , . c . - ^ e . o eI-25 
— - FIND* . .... o o ... o o . o , o o c . e l~16/23 

— definition of- cc.c.I-3 

— initialization* * - . a . . o . . . . . . ,2-3/4 

— loading, « c c c ~ c c c - l^.^ 
~ signon screen. „ e o « <» a * = a * = « - c « € = 1-6 

~ special capabilities . ^ e ... . . . 1-29 

™ system component s o o « s o c o ^ e c o e 2-2 
-~ rs . BASIC . c - . o , e ^ - , , . c = c d-n 
PS^IIAL lamgmages 

— applications a f * c , , o <..•.> . , , ;: . . .. o3~2 
data types c e = . « t * = c c , . a * - . c 3-3/? 

— introduction, to ... . c .. * c .. , , , . - 3 -2 

— overview. « * . <> c „ c c <• * * c « . * c « s 3-3/6 
— - names o . « o © e o » • « * o • * * * e o *» . © o o « 3-7/ 8 

— reserved words. c o ...... c o c 3-7,L-2 

~ rules for. • . o . • o c c o • . 8 o . • o • . s oi-18 
~ syntax diagrams o o * c . . o « aa . o c G p=-3/8 

PRO QUIT (PRGC; c o c o o . s c , , , c c c c4=-44 
PUT (PROC) , 9 o e o e c c o o 1-10,3-37^4-44/45 
PUTBLKF (PROC) * 9 6 o . 9 ..... & Q . . 4-45/4 6 

PUTF (PROG) o o a o . e a e . . o o o e o e o e 1-22,4^7 



QUIT (EXEC cmd) eoo CO o 00 c C3 2-38/39 



lata cyp< 

r hz al =■ 

lumbers. 



._-.a-j --r i-„ ^. i . - . :..^n - a3_ 1 

PJEPl'lE^ 1 ??.~ " % . = - < - - - • — r/5' 

Pedirectian, 7/C = e . 1-23 2-! ^ 

REFUGE statement , 5 = = 3-23/ 2« 
Relative file srnport '"C64^o , . e . .M-I/5 
RELDEHO - S (sample riogran) o , , . ,!d-f < 
RELOCATE ^-ility. . c 6 t o - - ^ e 2-11/ 1 5 
RELOCATE - S ^atiiitj program^ o , o , « e ,0-3 
RENAME '^EXEC cmd ; , , c c c . . a c c 3 . 2-3S 
RENAME (FUNG) & <, 3 , , e ^ c c o , o . a G 3 4-50/51 
REPEAT srateinent c . 5 . ... - - . 3-2? 

Reserved *rords s . c , o - , ^ c . c . . c c c 3-7^2-2 
RETURN key e 8 . . . « _ c o « 6 o . . „ * c 2-5 ,2-46 
RETURN staremenr , o , o c e , , e a ^ , c 3-41/42 
Reverse video c . & c . - , , & 3-1 i 5 4-*-: 3 s 4-45 
RS-232 supporc. . o e , , 9 , c c e c o c 6 • cF-1/6 
Runtime errors . » ft , « s « « c e c e « = « c C-2/3 
Runtime errors s locating c ..0=00,00 oD-i 

Screen (5) device* o • • . * . . « . 6 e . « 2-12 

Scrolling, left 5 right o » o 3 c . I -20, 2-47 
Scrolling, & doTn, , - . . c . ,1-16,2-^7 
SET (EXEC c^d;. e s 9 .»..ooo 6 3 _c2-o9/4^ 
SETP0SF (PROC) ^ APPLE 11) - « = . o . . . 4-51 
SET PREFIX. (FITNC) (APPLE 11; c . . . . . 4-52 
Shift operators o c . c ^ , _ . c ^ e _ 3-22 
Signon display c o , c c , c c o c e t o c o , . c 1-6 

SIN (FUNC)o o e c * o = o o . e e „ o o „ e , e e o e o « cK=i 

SIZE (EXEC csd)^ e . 8 oc 3e;e , 69 o 5 2»40/41 
SORTDEMOeS (sample prog. ) . e l-30/31,Q-3 
SORTSTRING. S (sample program) . , , . o c Q-3 
SPLIT a S (utility program) « . . . . . = , c c Q-3 

SRECE1VE.S (utility prog« ) . F-4/5, Q-3 
SSENDoS (utility program) . . . .F-4/5 » Q-3 

SQRT (FUNC) o o e a . o . . . o . . . . . . . . o . . . . .K-l 

Stack overflow. v ....... c ...... s • . .3-47 

Starting, system, , *»o«o> . . 1-4/6, 2-3/4 
Statements =0 s * « o3-25/34 

— (=) assignment* c * * * » 9 . * * * <> . * o »3-26 

~ BREAKo . e o o o . e o a a o e • , * o o e . .3-31/32 

~ CHOOSE e .oocc e . sec ooo e o 8S . e . 3-30/31 

— ESCAPE & REFUGE. , *o, » .3-33/34 
~ FOR. 3eo *. e *. . ea0 c,oo 03 o.. c 3-29/30 



Copyright (C) 1985, SMi § Inc. 



■ : 



— WHIJ 

7 ~ ; ' 

r 772 



ian 



I! 13 



— =- _ 7= ir t- . < - , . - -1 c ' -r- 1 / 5 ': 5 -' -3 

~; 7 .7.. J 1. ': < x" . - ' -a - c & z „ - '-. _. • -: - ? - - .-v.. J. 

— ler.gcl.* : .. c 4 -7 ^ / 3 C 

— 2C?c - . . c. o . c , 3 £ , , 3 c = = . ^ = ^-33/32 
s ear h dug = c . . _ „ 4 -2 5 . 2 2 ; 4 -2 , 4-5 5 

i£RE-L ;r;y=j - c . , ^ -27/ 5 3 

STFVAL uU^rr* o .- o - - . - c. • , e - , 4-53/5$ 

Safer-j-^rir^s t = , - 1 - 2-'-:l . ; 42 ; 3~4'-/£ / 
™ massed argetner^s . = « : e , _ = . 3-42 '45 
iSb: def ir^c c . .- , . . * _ . 3- 4 ~7 

SUB3T1 (iUMC) „ e . ^ . - c c & , _ . o , . 
Syrxs^ diag A -aus : dcT 7 ; rai:. , c : = £-1 "2 

Syntax diagrams . .. , ~ . ~ c ~_ -r~3 # g 

System data areas o t - G c - c , » . i = 9 * , 



r c 



7v721 data rppa- 

^7133 7a ^33^ , - - , = 

~ aid ecic ruf?5i • - - 
™ a-?: to ^pd£-e after editc 



2-5^/:2 
- .2-54 



— clearing c . » . . . * . . , , c - , - ^ . . 2-^2 

— -;ririr £ g 2c t , £ . ^ , ~, c , ; - « c , . 2-iC 
~ V 7 aevici . - . a c- c . - 3 _ o - - = . 2-15 

^2XE'3 -cc x - . - = - a - o c _ * . - c , , , . 2-43 



IIHYIERIio 2 ~ as :j 1 -c s r c g az ) 
22 keyror ^ . s . , f e c ; , c . „ „ 
77SI"2?2 '7 - 'im;. ; ^ . 
227P2ER '217 T 3; , o . . . - 

7 C O C 6L£I 2 3 c t " e ..a 

777E "* I x c ^ c - c - 

TYPE (EXEC cud) ....... 



SOE cperct^c^cccc ,3-17.3-21 22 



Z AFFILE (FUNC) 



U 



U3IL2Ar EXEC csd) o . ■ , , . ; , 3 . - e c = c , 6 2-42 
UNLOCK (EXEC cad) . : c , 2-42 

UNTIL byword e • • , , s c , . = « . c . _ - ^ , , 3-2 9 
Unprintable ccces s embeddi^gc c c . , ,3-11 
Upper 2- lower case acaa (CS-i) « 3 c = ,2-55 
dpper esse & graphics eede (Cc-p o C 2~55 
L : ssr-"def ined r-oxiratids e „ * = * „ 2-4 

User-defined sprout ine^ - 8 c 3-4l 2 7 



— arrays s declaring c , , « c 9 e e » « 3-1^ /1 5 
™ command line argument « « * * . « 3-56/57 



Copyright (G) 1986. SMA. lae. 



I£ 1 a T ? ¥ C £-£ ^ L : 
C IPEOg rammer ' s Micro Application Language) 

AN INTRODUCTION TO THE PROMAL PROGRAMMING SYSTEM 
For APPLE lie 5 lie and COMMODORE 64 Computers 



SYSTEMS MANAGEMENT ASSOCIATES, INC. 
3325 Executive Drive 
Raleigh NC 27609 

Rev. C - Sep* 1986 



Copyright (C) 1986 SMA lac. 



Rev. C 



MINIMUM HARDWARE REQUIREMENTS 

- /. • . . o IT" . o ~\ = - - "'le- - ' \ o o . : . O-Oor.r- . - - -'->^'^ . ' , . 

- *■ ' - 

' rov* r - :: r :r o;o-~ s r lo- - - 'jl' . c. •. - f- - ?eoL-Z-S- ' r c ZOZ 2 .' ? • : ?r r r:il 

• ^ - . " . ci : • s r ~ I>io * o.; .' i::: . : . d:o~ ' " 

x r* T 3"":* S o r & q ^ i v : 1 - rX -a u or: s-;p^iS Ion icr / 1 els k . 

c.--::r.-- e: o ~ Li'O lo ... : ' z-z cc.rf c o £• / cc : *- o t zz MSB 

^ri\e. Z.c '"; o „ llzzc " 5 Iuiic ? c~ ir c ?c ~ ;oi: ore i.i. ccpat- 

i? 1 -:i IriC/l-.I, .: ; erotic ... on ^:g„c . -..n-:.v. ITo/rl^L L c"cr- £k.~ o.AL 

! oe I^oTiSf V o. i. 1 c - 1 n w --'hic\ copies the reading s p e c : ?" 1-41 c; . .: ; ' risk 
drives « This feature can oe d i sab led if desired • PROMAL is conpatille «ici 
the Skyles 1541 Flash and ISSE Flash, 

CCPirlGHT kCIICr 

Copyright j 984, 1985, 1936 Systems Kapsgener: As?oeisces s Jnc . 

A* I rigors "reserved w~r Idv-ide , manuals and programs- 

TRADEMARKS 

P ROM;- v c '.c I YNODISK are trccer^iks of Syc cems Management Associates ? Inc. 

Appl , Ap '._ ~ II, and ProDOS are trademarks of Apple Computer, lac c 

Commof ere and Commodore 64 are trademarks of Commodore Business Machines, Inc . 

Thund ere lock is a trademark of Thunder^are Inc. 

Ramwci <c£ is a trademark of Applied Engineering. 

IBM is a crodemark of International Business Machines, 

1541 Flash is a trademark of Skyles Electric Porks. 

DISCLAIMER 

Systems Ma nag err en.-" ^sscciales* Jccc ms:;es ~c claixs or 7 arrar-ties > 7 ith 
respect to the center r ? ^ c " - - s " 1 cl^cs; 1 ^^ or ee prcr: f r describes, beyond 
the limited warrant * included w± : : a t~e o "od ict Further t^e rig^t Is reserved 
to ioake any changed ':o chxc pctl izscior o_ toe predict i. z describes * T i thout 
oo logo z ion to nocofy a c y p f r s o ~ f s ... c e-'is i c o or ohar.ges 

NOTICE F RCH %PFL5 COMPUTER INC. ?CR APx°LE VCSSIO^ 

ProDOS is a copyrighted progiao of e.D p- 1 e Computer. Inc-* licensed to 
Systems Management Associates 9 Inc. to o is or ibute for use only in co"ibinat ion 

with PROMAL. Apple Software snail not be copied onto another diskette (except 
for archival purposes) or into memory unless as part of the execution of 
PROMAL. When PROMAL has completed execution Apple Software shall not be used 
by any other- program^ 

Apple Computer inc. makes no warranties, either express or implied, regard- 
ing the enclosed software package f its merchantability or its fitness for 
any particular purpose* The exclusion of implied warranties is not permitted 
in some states® The above exclusion may not apply to you * This warranty 
provides you with specific legal rights^ There may be other rights that you 
may have which vary from state to state. 
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MEET PROMAL! 



Congratulations ! You're about to meet f 
programming environment you can buy for your 
in conjunction with the PROMAL Demo Diskette 
with PROMAL. 



e >i l 1 y u get acq - i. ~ r 



et the name 




IS ECT CGF Y-??.OTSCTSD 4!£ 3SCE 1E2 S24L 18 lIlOFXi; Gil 72S SYSTSK DISKETTE IT 

GA110T 3fi SlTUSJfiC FOE A HfUlFo All the files referrea to in chis MEET* PROMAL 
manual will be f conn on tne PRGI-AL lame- Dis&ette* Tins v;a y /cu can satisfy 
yourself thai FKOKAL is overselling re ic :c, ve van! you 1c cs 100 parcenr, 



We do not claim that IIOrllL is for everyone. PROMAL is fcr the person who 

has a working familiarity ^ith zhe computer and BASIC \ or another high -level 

language), and wanzs co gee the aost from his or her computer. If you are 
frustrated by the limitations of BASIC but want to avoid the complexity and 
low productivity of machine -language o r c g r a mni i n g ; then PROMAL is for you. If 
you want to realize the full potential of your personal computer, you need the 
power, the speed 9 and the capabilities of ? ROKAL o 

mom this maotal 

Year PROMAL system includes four manuals plus Appendices and an Index • 
The first manual, "MEET PROMAL! " , which you are reading, will not make you a 
proficient PROMAL programmer 3 bat will provide enough Information for you to 
evaluate the PROMAL system. The "MEET PROMAL! " Manual Is required reading for 
the owner of the PROMAL System; please do not attempt to study the USER'S GUIDE 
or LANGUAGE MANUAL until } ou have read and executed the examples in "MEET 
PROMAL! " o This approac - vi 11 help even the advanced programmer get the most 
from PROMAL o 

WHAT IS PROMAL? 

PROMAL ( PROg rammer * s Micro Application Language) is a high-performance 
programming system^ It includes: 

* An interactive Command EXECUTIVE 

* A Full-Screen EDITOR 

* A Structured Language COMPILER 

* An on-line LIBRARY of predefined subroutines 

The EXECIJIJLWE lets you enter commands to load and execute programs, to 
manage files and memory, to display files and directories, and to do much more. 
Many built-in commands are provided , and you can add as many of your own 
commands as you want • 



e a 1 - s 




AUDIENCE 
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k: t?;oogh your ore* Ice? erpsriaiooe r . T i th BASIC i- i 1 1 oe helpful io ulcers tsrd- 
ir.g FkOk^h, you 1 flea \ery neck or? I i- ciioe^soro- Sore aspect of lkC*Ki*L 
may seem strange at c i ~ ? c , bjt you 1 ; 2 ccr. ape :ec ic :e I :s simple elegance. 
knr.e you ha-~e naste^ed s basic concepts, you -"'11 r:r? r ROMAL much easier 

to ircgras tcao 3 AS IC cor sr 7 non-trivial app lie at ion . 

imf E GST STA££iQ! 

If re ready to begin your guides tour, get your P ROMAL Demo Diskette, 

ycer computer : ard read on • •• 

3U?LISATI1£ THE 11EMO DISK 

Because the Demo Diskette ceotsins important files o T h~° eh are set duplicated 
or. the sealed System Diske tie, you should nake a copy cr the Derac Diskette 
before proceeding. The examples in MEET ? ROMAL leili ^rrite on che demc disk. 

Therefore you should ^ : iX^^ s hfL±jh € .. cc ^Z f 30 " n a : f Gl1 ^ a ^ 8 s mistake cr 
accidentally overprice or delete a e f ycc v 7 i l i still ka^e trie original Demo 
Disk o Yc o o^-e copy r~e D-exo disk -it^ .o~-y v irid of disk oory program 
uommceore oioners --jfrc don't ha- ? s £ copy program can use the DISKETTE exility- as 
described in Appendix Go Apple users can use the standard Pro DOS disk copier 
furnished on the System Utilities Disk which came with your computer. 

LOADING P ROMAL 

For Apple II § 

Put your copy of the P ROMAL Demo Diskette into the disk drive, close the 
door, arid turn on your computer o If year ccmpater is already or. = you can hold 
dovjn the CTRL and open-Apple keys and press RESET c 

If you have a hard disk and v. i s ti to hoot from hard disk, create a new 
directory, and copy all the files from che Demo disk onto i t . The volume name 
for the Demo Disk is / P ROMAL/ . Then execuoa ? ROMAL. SYSTEM. 

If you have a Ram works II or similar /RAM disk and want to use it with 
P ROMAL ? first install your /RAM device as usual* Then execute PROMAL. SYSTEM. 
This can be done from BASIC with the command -/ PROMAL/ PROMAL. SYSTEM. 
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128; 



Please rollcw the f I lo" l-.g £ I *- Z i CcrT^Lt.ll^ 

1, Turn on your = : c/c _ar : he «. al manner- 

2. If you have a Commodore 128, you most type GO 64, are -scly I „c i he 

"Are you sure? r p~ riiC t « PPrOMAL works only in Commodore 64 raocs «, ro ::c: 
attempt to use 128 ncoe or ocr.~l 541 compa-ib Is disk features cf _ke If 71 cis v 
(such as dou ,v r:o: e o\ : fas t u mode". 

3~ rose:: *: ~ 7 ?-r.r copy cf :'~-e jemo Dis '~ i i . ere drive, close the door and types 

LG&D ^72mAlI\Z \'RETURN> 

•r If the asly perip~~r*l ::. ycur sys ten "l - single 1 ;h> 1 or 1571 disk 
drive 7 proceed to step 3* Ike Commodore 64 „on of PROKz-L i nc luces 

r-YNODIS£ ? -hick derbies rhs reading speed o ^"e Comae do re 1541 or If": cisk 

drive This feature is comparable to many other disk speedup products which 
you may have or may have seen. PROMAL is compatible with Skyles Flash products 

provided you disable DYNODISK as described below. Do not use ? ROrtAL with any 
other disk speedup cartridge or software package unless you are sure it does 
nor use any memory in the Commodore 64 and is completely 1541 -compa tible ; 
otherwise, PROMAL will not work proper iy e BYrkODlSR works automatically with 
ail PROMAL programs; there is nothing to Install- DYNODISK has the same 
limitations as other disk speedup products - rameiys 

( £ ) You can't use DYNODISK if yor. osre any other device s uch as a rrmter 
or second disk drive) attached to the computer on the serial bus. Therefore : f 
you have a printer r yoa should either turn it off while reading from disk ; or 
disable DYNODISK as described b Q iow If you decide to leave DYMCD1SK enaoled 
and turn off year printer, and you have a printer interface (such as a CARDCO) , 
you will need to turn it off too (in che case of the CARDCO G-f, this means 
disconnecting the single wire froir, the back of the computer) o Fai Icre to 
observe this precaution say cause the computer to "hang up f % necessitating 
reloading PROMAL* DYNODISK can be re-enabled by a simple command when PROMAL 
is running* 

(b) If you don't have a 1541 or 1571 disk drive, see AffllBIX 1 before 
continuing o 

If you need to disable DYNODISK, type; 

POKE 3555 ,§ < RETURN> 

5a Types 



Ell <RETURN> 
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The system will then load " )R, EXECUTIVE, and LIBRARY* On the screen 

you will see; 

LOADING EDITOR 
LOADING EXECUTIVE 
LOADING LIBRARY. • • 

The screen will th _ . c d displays 

PROMAL Development System EXECUTIVE 

Version 2.1 
Copyright ( C) 1986" SMA Inc. 

PROMAL is a Traders ' 
Sys terns Management Associates- Ir_c . 

At the end cf the s igno^ lr. f o^at ion , you will see (unless you have a 

Thunderc locV; carf ir. an A.?p le II : "stem, which sacs tr.a date automatically) s 

PLEASE ENTER TODAY'S DATE 
; in the form MM/DD/YY) : 

Type in the correct date, for example 09/30/86, and press RETURN* PROMAL 
uses this date to automatically "tag 11 all compiled programs with their creation 
date, so if you make revis ions to a program, you can easily see which is the 
current vers ion o You will now see; 



Apple II 


Commodore 64 


FI = EDIT 


Fl - EDIT 


F2 = PREFIX * 


F2 = DUMP 


F3 = COMPILE 


F3 = COMPILE 


F4 - GET 


F4 - GET 


?5 = FILES 


F5 - FILES 


F6 - EXTD1R * 


F6 - MAP 


F7 - HELP 


. P? - HELP 


F8 = COPY 


F8 = COPY 



These lines tell what the default function keys do. On the Apple ll 9 the 
letter "F" may be replaced by an "Apple" icon, On the Apple II, a function key 
is activated by holding down either Apple key and pressing the desired number . 
You may use function keys to quickly enter commands when using the EXECUTIVE* 
Now lets begin our guided tour of the PROMAL EXECUTIVE. 

USING THE PROMAL EXECUTIVE 

The " — >" is the PROMAL EXECUTIVE'S prompt, which indicates that the 
EXECUTIVE is ready for you to type in a command. Try typing thiss 

TYPE README eT 



Copyright (C) 1986 SMA Inc. 



Rev. C 



Now try typing; 
hello 

£ollor-ad of course by <RETURN>. You should see; 
— > hello 

PROGRAM OR OVERLAY MOT FOUND : HELLO 
— > _ 

Here's what happened. TJ hen you typed ;i nellr 4 *- ? v •'• : -LI .: "z^z zz ~r :e - : e 
command called "ne 1 lo i? t Since there is no baiit-in command c-llec * : helio : ' the 
EXECUTIVE search e: fcr a us -:r -de fined coitKsnrf file e~ disio Since . ': dinn r 
find the command file "halic f % it gave you an error ? and is now ready for 
another command „ Ta is is hoc PROMAL executes commands • riict it loo he for it e 
command in memo ■ j ; - 'id then, on disk. (You can create ne a- commands oy compiling 
a PROMAL program c ; Unlike BASIC ? yoj. c an have several programs i - memory at 
once, and execute any of them by just typing the name. In f ac c - the EaECJCIvL 
and EDITOR are just compiled PROMAL r.: grams that a :s - Ireac y in memory! 

Now press function key F5 (for Apple II* hcif do<~~ eirher Apple key and 
press 5) • You will see "FILES" appear o This is a bni^-m commando Press 
< RETURN> and the EXECUTIVE will execute the FILES ccr.jianCc Try it, Yen should 
see a list of file names c On the Apple these names will be displayed in f oar 
columns. On the Commode re f/ the display T -ill be similar to a directory listing 
made from BASIC. 

These are the file names on your deec diskette* No t i z z t lat nest cf the 
filenames end in - ? • C ff or \S r c This is because PROMAL file names have a single 
characcer file extension after the name which tells T vha t kind! of file i c isr 
"cC n files are compiled command programs and n . S r flies are PROMAL language 
scares : % text) programs which can be edited * There for z FIND? S is a source 
program and FINDo C is the compiled (executable) form of the same program* 

For the Apple II only 9 yon can get more information about the files on the 
disk by us i ng ^ command ( EXTended DIRectory) . Press F6 (Apple key 

with 6) f ®r type EXTDIR * and press < RETURN> « Be sure to type a space Def ore 

the asterisk* You should see a list of ail the files 5 with information about 
each file, and a summary showing how many blocks are free on disk. Unlike the 

FILES command 5 the EXTDIR command is not built-in to the EXECUTIVE. Instead, 
EXTDIR is actually a PROMAL program which is loaded from disk and executed when 
you type EXTDIR. 

IMFQETAlls For the Apple 11 only, please note that if you change disks you 

wilF = in^eT == t^o~press F2 and <REIuII>~af ter changing disks to issue a PREFIX * 
command • This tells ProDOS what the new volume name is; otherwise, it will 
still look for your old diskette, probably generating DEVICE NOT READY or FILE 
NOT FOUND errors « 
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l>j IT ^"l-S^ 
FILES [ Dir ] 
FILL From To Value 
FKEY [ NurAe- String] 
GET Command file 
JOB FilecJ [Arg..,] 
MAP 

PEEFIX [/Palh: c: ^ 
RENAME file Newname 
SET Addr Val [ Valo , 

TYPE File 
UNLOAD [Command] 
— > _ 

The display above is for the Apple lis the Commodore display ".fill differ 
somewhat. The top four lines are clues to using some control keys for line- 
editing while you are in the EXECUTIVE. We ' 1 1 get to them in a minute. The 
rest of the lines summarize many oc "he most commonly-needed command s ~ Many 
commands need cr may have arguments after che command name. These arguments 
are usua 11} file names or numbers^ Arguments shown in square brackets ( [ } ) on 
the help screen £re optional • For example, DUMP needs one argumc-. ~ r \7r zr" . 
and can optional 1 - have a second argument ? "To". Try typing this ? 

dump 1100 

You will see a display similar to i 

1100 72 65 7A 85 72 A5 7 1 55 rez s r e qa 

The actual numbers and letters shown will be different « This is the contents 
of memory locations 1100 hex through 1x0"% displayed in hex and ASCII. A ,f 
is shown for any byte which doesn^t represent a printable ASCII character, if 
you're not familiar with hex notation, don # t oe concerned; later you may want 
to consuls trie reference manual for your computer to learn about hexadecimal® 
DUMP with one argument will display 8 bytes starting at the FROM address • 

Now suppose you wanted to dump from 1100 to 1180* Wait I if you think you 
know, don ' t type yet! instead press CTE3L f and while holding it down, press 1. 
What happened? You should see; 

— > dump 1100 



tl - PREFIX * 
f3 - COMPILE 
fi = GET 

' z - '"."LBS 
f6 - EXTDIR * 
f? = HELP 
f8 = COPY 
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... ;;. lhara ari : .: .. nj . ... z. .. ci:: ^ .. nr. nr ;. :.. ... :. . rrr na'ii . . 
thasa _nlil •« li: ^ 2 rh^ hi JI _h _ -lens ^ , .« to experiie..: ri^hc now 

using the clues given by HELP) • 



Cne Txre rhlag fu-.a: ZZ^l~B ~ try pressing it Sr^ral ; haes c Whet happens? 

You can * : backtrac k ?s taro^gh prior commands, cr.e a; a tisi, niter you get a i 1 

the :?ay tack : : ~- "~h- s t c v r c- f the aessici hefcne --h?^ :.~ t h e dat^' ^ t --.e 

nez; CThl-B ni ^ ^nrap ai ranch 1 agaia to the ma s ~ rs:iL: ccir_*<iand. 

WRITING A PROGZhM Tlhhh. T£l 

Now that par knar a Utile shea:: using the EXECUTIVE. is: r s : rp rriting a 
program using chr ihllih. i^es^ ZT1 arc <RETURN> (or type Ihlrh . ^lz::s: 
instantly the screen ri 1 1 clear? a /: a p t far taa bottom 5 _:-3J -''hie a snem 



LINE = i 

1 = DEL LN 2= INS LN 3=MARK 4" RECALL 5=FIND 6= CHANGE 7=HELP 8=QUIT 

The tcp 20 blank lines form your text area € ad the bottom 3 lines are a 
status area ^ which tells you that the function ne> s have now beer, recie fined <, 
On the aorrraof ore S~ . these function key legends occupy two -column. iin.es 
instead of one as shown above • For example, Fl now raeaas ' f deiete iine" : h You 
wo a * t need ar.y c f these function keys (except F8=QLIT) :.c edit your first 
PROMAh arogran 

The blinking cursor is at cha top of che screen It alanys indicates vrhere 
the next character you ,:>"pe -ill appear c Try typing in trie f c 1 lowing program, 
exactly as shown below. Ee err? tr si art each line in the 1 i r ? t column $ and 
use <RETURN> to end each line. 

program hello 
include library 

BEGIN 

PUT "HELLO YOURSELF !",NL 

Ell 

If you make a mistake, use the DELETE key to delete characters * Yon can 
use the cursor keys to backup and oner-type any corrections too* Yen can type 
in upper or lower case or a mix - it aeesr't ma t cer <> If you prefer upper case, 
you may want to press CTRL -A, vhich Fill carse ALFHALQCK to be displayed in the 
status area. After this, any alphabetic keys you type will automatically be in 
upper case. 
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The I L:;>; . Iils _ .1 your progr? a. - _c 2 r^ire yil L_ H^A; 
-rih^I 7 ogre.:., scares ",i:1b way • ^ -<e :.; _ir'e ---Li - "V- r :-l ;c " v: l a " _r.~ 
r irhr. jt'.-.es it„ "he built in. LIBRA?. I.* , To r -ill ncrr:.£lly ^se che INCLUDE .dSr^RY 

scatancert in every program you writs Ine iJ L£SiM f? line tuerely iiicicaces the 
start o c the -. ^ i n prog ran - The ne t iLiie is the ^ go stance c f ycer litcle 
progr^r;. PUT ^2 siniiar ro s liiS 1C PEI^T^ sad px.ir.t3 scrings ox :riarscte:£o 
r ':.'. 1 : i- e 1 h I *" - -F^\, ^ •; ^ * ~ S-.O-lri-L 6 x. p i i 1 1 ~ _ y trhsn y c v.. carl tr sta-"~ a '.:« 7 
line c The JL dees this ( i ': stands for New Line) . You can also use €R 
(Carriage z e -ur rl :~ pl^~e r f r'L ; the result is the same. 

When you' re done press F8. You will see a ci splay similar that below. 
The numbers on your screen may be different (especially or* a Commodore 64). 

This display shows your choices of what to do. "WORKSPACE" : is a small, 
iii-memory file with the name "W" . It is useful for tempers?-: ^y scoring a small 

source program you are experimenting with, without saving ir a i s s 

Press if and <RETURN>. Immediately # the cursor will re-appear below the 

"SELECTION? " prompt , Hi is indicates chat your text has been written to the 
workspace (it's fasti) f and you may now make another selection. 

PROMAL EDITOR. 2d 
Copyright (C) 1986 SMA, Inc. 

BUFFER SIZE - $882 

FILE NAME - VJ (AUTO UPDATE ON QUIT) 
FILE SIZE - 66 

OPTIONS 

R - REPLACE ORIGINAL FILE 

N = WRITE TO NEW FILE 

W = WRITE TO WORKSPACE 

C = CONTINUE EDITING 

Q = QUIT EDITOR 

SELECTION? 



Type Q and <RETURN>, and the EXECUTIVE prompt reappears; 
— > 
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COMl-,- 4 1^ : .251 PROGRAM 




PROMAL DEMO COMPILER 2.1 

Copyright ( C) 1986 SMA Inc. 

READING LINE 2 
INCLUDING LIBRARY 
READING LIME 67 
RESUMING FILE W 
READING LINE 68 
COMPILING <MAIN PROGRAM> 
RS^DiuG LINE 70 
HELLO compiled c 

70 Source 1 Ines 

$0025 (3 7) bytes Ob j , 

$0 Scalar , $0000 lO) toe* Vars • 
Table usages 

Symbols t 36% Fwd . Refs : 1% 

Strings t 1% 



— > _ 

The display may ^i^^e' - garly ? especially for whs Co^jwue $L Q Ibe 
summary at the end sho^s i af oriaat ion about fcne obf.ecc 'Lie. t n>£ icnpller 

wrote to disk. This object file Is your executable crc^raii : ;*i -:h the default 

name HELLO, C, 



You may be wondering why the compiler said it compiled 70 source lines (less 
for the Commodore 64 x Your program was only 5 lines long! The answer is that 
the INCLUDE LIBRARY line of the program caused the COMPILER to read another 
file called the LIBRARY at chat point in your program. Later when you start 
writing big programs 3 ycu can tell it to Include other files of your own . For 
example $ you can tell ic to INCLUDE some file of subroutines. In this way, you 
can share commonly -used routines between many programs without having to 
re-cype them or "paste" the® into your program^ The LIBRARY file contains 
about 63 lines of standard definitions (59 for the Commodore) that you will 
want in nearly every PROMAL program. Like the Workspace, the LIBRARY is a 
memory-resident f lie * 

The summary also talis how big your compiled program is (37 bytes) < how 
many bytes are needed for its variables (none in this case ) ? and some 
information about how much of the compiler's internal tables were usedo This 
is described in the PROMAL USER'S MANUAL . Don't be concerned that your little 
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IXlLhdl^i . ... _ 

I , your program is ready to execute • 

Just type; 

And your program w: 1 : : _ ^* 
HELLO YOURSELF! 



— > _ 

When your program finished , it returned control to the EXECUTIVE . You have now 
created a new, user-defined command for the EXECUTIVE! Your object program is 
saved en disk as file KELLCoG 9 and be run anytime you type HELLO from the 

EXECUTIVE. You car. save as many commands as you want on as many diskettes as 
"-en Ii v e- Z-~ execute e command . just type its nan? If dr's been executed 
before aiu is in memory, it will execute instantly If no 1 7 che EXECUTIVE wiii 
FeLcn Lc r^or dis ; and execute i •: - 

?c:6 t you have .ic": ye saved your scarce program ( the :e "z file -ov: can 
edit) on. oisx; Ic*s only in che temporary workspace. Normally, you ~- 7 i 1 1 want 
tc save your scarce program on disk when you exit from the EDI Tor If you want 
to ? yon car, still save it now, from the EXECUTIVE, by typing COPY V: MSLLO. S 
•*nich copies the Workspace to a new disk file called HELLO. 

WHERE DOES PROHAL FIT 111 ?3£GRAM? 

You might be curious ~o know where your program is in memory . Types 



and you will see a ? * : aiap ff of memory , which tells where P ROMAL put your program 

and how the remaining memory is allocated. The top half shows information 
about what program(s) you have in memory, and the hoc ton; half shows a summary 
of available space. We won't go into all the details of the MAP display here. 
It is fully explained in the P ROMAL USERS GUIDE. 

Apple II 

HELLO ( PRO.) • 09/30/86 CHKSUM 49CB 

CODE $2900-29FF 

OBJECT PROGRAMS $2900-29FF (256) 

FREE SPACE $2A00-8DFF (25600) 

SHARED VARIABLES $8E00- (0) 

EXEC. /EDIT SPACE $6IQ0~8DFF (11520) 

TOTAL- SPACE $2900-8DFF (25856) 

ACTIVE WORKSPACE $1200-1241 (66) 
FREE WORKSPACE $1242-5AFF (18622) 
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Comm odore 64 




StiitlEl 7A?IABL*S 3-1 JO l'C) 
SPACE ^fCG-CrTJ 



"c; " v - ---77-=- "^'Si'::.; yor nay n%~— l"; v o r ^grains: in nancr^ ( I XT I" IE. snc 
HEL1C) , cr jusc one if yo a didn't try EXTBIR before- Tee Commodore version 
shors r~ 7 c "cgrans in memcr^- oiliPlLE sad yeLi HELLO program^ Since che Lp o 1 ? 
has some^he c less memory thao che Commodore* bat hes a rel&cively .as; ci&Xj 
the Compiler is alr^vs o^Ieadel n-o:v?£t ics lly -hen it finishes e le^^irg ?cr? 
root: for otner programs* Sines che Commodore has £ 1 i _ t _ e icre available 
memo ry but a ^lc«~ disk, IP^TKAL normally iceaps the compiler in memory w'aaa ic 
finishes so you v/c r " : have lg /a i t fc.: it to ..cad -her, y: r, need it agar — 
The number s:; ran :: CCDE :: eh :--\ v 3 the address inhere von.:: p:: eg ran. ;*as loaded c 

If yon executed another program^ a part of PROMAL exiled the loader would 
pat it right above where HELLO ends e PROMAL always allocates programs and data 
or, exact "page 11 boundaries in memory {that is ? the starting hexadecimal address 
will always end in 00) • Technical!; ~ PilCMAL programs are known as 
"relocatable 11 object code « who on rr-aans that they can be run sawtiere in 
memory* In the event that you use up so much memory that roera i s n " r, enough 
room to load the specified command program, PROMAL -vill automatically 'unload" 
programs to make enough rco? - The MAP also tells ether information about your 
HELLO program. It tells yen it is a PROMAL program, Lna^ il ras ccmpilec on 
i 1/04/85 (or whatever aa.ee you used), and what its "checks ant - is. If your 
program uses any ^ar ish r,es (your HELLO program doesn' -} ft shows what space is 
allocated for variables 

The checksum requires more explanation* When PROMAL loads a program into 
memory, it computes a 16-tit sum of ail the bytes loaded * This is the checksum 
shown, in hex ♦ Anytime you execute that program. PROMAL recomputes the 

checksum and compares it to the saved value . If the two values don't match, 
the loader knows something has corrupted the program in memory (such as another 
program POKEing around where it shouldn^ t i ) « The loader then automatically 
reloads the program from disk* This provides an integrity check for your 
programs. 

The meanings of the rest of the summary are described in the PROMAL USER 
GUIDE. One thing you might be interested in now though is the line labelled 
TOTAL SPACE, This is the maximum amount of memory that you can use for PROMAL 
programs; about 25K bytes for the Apple or 33K bytes for the Commodore * 
Although this amount is somewhat less than is allowed by BASIC, you can still 
have PROMAL programs that are much larger and more complex than is possible 
using BASIC, because P ROMAL programs are much more compact • For example, the 



Rev. C 




h r _\«_ •. 1 jig j rr ° — ] 1 ; re r " c ; ~~ ~~ rr r " r-'h on 5Cif r: • : s chri -; 1 

concepts behind the power : f the PROMAL System. 

,2: : -: s~: r ; r ~ *i r )" T T 

_.e :. - -y ah:rg c. ?- a"; 1 : nange ::c ~;our program, Re-enter the EDITOR by 

pLcbSiug 31 ana \ ftiTu'S/*^ c lour program will reappear in the text area cf zzs 
cfsp'sy t ical! y 3 

Use che c -j r & c r keys cc cos icier the cursor over Ihe E 'Y" xr YOURSELF 1 ' ir- 
r*e Co"rs"h iine„ ? 7 o^ cress if /ca have 2: Apple 11, cr CTSL-bac^sirror: 

.'cne key uc tne left oi tae i :i Key) if you have a Commodore 64 * What 

happened This key deletes £ character, hue unlike the DELETE key* it pdil& 
all ens texc or, ;he line cc the right over to ' fill in the hole ? *o Press this 
rsy 8 note tines :o gee rid cf ?: YOURSELF 1 iC - The lire scoria lech tike thi s s 

1 IT f *n£hhO ' : : mL 

Nov* put the cursor over the N in 8f NL ,f and press CTKL-E if you have an Apple 

or SHifr-iKSl if you have a Commoaore o The highlighted word INSERT appears in 
the status area at the bottom of the screen, indicating you are now in insert 
mode « In insert mode anything you type iciii "push over 11 the text to the right 
of the cursor. With insert mode on, type; 

frcE year cursor position. To exit from insert mode, press any cursor key or 
< RETURN> • Your line should now look like thiss 

PUT 11 HELLO 11 j CARG[ i J , ML 

In PROMAL? square brackets are used to enclose array subscripts instead of 
parentheses as in BASIC, so you can tell an array from a function easily^ CARG 
is an array which is pre-defined (in the LIBRARY) for a special purpose. CARG 
is short for "Command Argument", The CARG array is an array of strings, which 
is automatically available to your program when it starts <, CARG[ 1 ] is the 
first argument on the command line, CARG[ 2 ] is the second argument, etc • 

Now press ¥8 to exit, and select W and then Q to resave your new version to 
the workspace and exit to the EXECUTIVE. Now re-compile your program by 
pressing F3 and <RETURN>. After your program compiles, types 

hello PROMAL 

What happened? Your program displayed 
HELLO PROMAL 
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low try typings 



It 1 1 r c^rer y body 

Whatever you type - 2 '~ : /ic -z^^^r.-: ic: i'-<- tc- ^ : : ~j nii the 

BXETIT™ \ tl- --^1: r, s l :~ 1 1 - > . „: : it- ?y?\- t— § 

1 • 1 *. : ^Ifnr and execntiwe 
Your program ;1L1 ~; r ~*7a; ~ 

HELLO EDITOR 

What happened to "and executive"? Why cidrr t i: display? Remember that a 
blank separates arguments 3 1 a command, „ Therefore "AND 11 got put in CARG[ 2] <■ 
and "EXECUTIVE'" get put :r CARG [ 3 1 ; because the EXECUTIVE thinks they're each a 
separate argument !hu-~ ; z B rzzi z zlj pricts C it US' I ] . 

7c ^ car force the EXSCJTIV2 tz aczepc a string rs th blanks v:: it e§ a 
single argument by enclosing it in quotes* Try thiss 

hello ?3 eiicar cad executive" 

You ivill low sees 

HELLO editor and executive 

If you were 00 servant and if. you were typing in lower case , you might have 
noticed another difference. Ordinarily the EXECUTIVE converts lower case 
commands and arguments to rprsr case as it reads their: in 3 But if you enclose 

an argument in quo tes 9 it won't convert the argument to upper case, 

Naturally you can do more wicn command arguments than just print triem. For 

example : you can use a command argument as a file name for your program to read 

or writes Our nexc exampie t#i 1 1 demons 1 cde how to Co thi» ? and how you can do 
even mere powerful ' : 1/ red irec 1 10a" on a command line = 

Mow that you've written e trivial PROMAL prog r a 11 ? ycu -.ray rant to see a 

program that really does some thing useful. In the next section we'll take a 
look at a fairly short bec useful program that illustrates a text-processing 
application., and illustrates many key PROMAL features, including using the 
LIBRARY* 

If you wart to postpone your exploration of these programs until later f you 
can simply turn off the computer. 

A PROMAL TEXT PROCESSING PROGRAM 

Suppose you had a mailing list on a disk file called MAILLIST.T, which you 
had prepared with the PROMAL Editor Q For simplicity's sake, suppose you had 
one entry per line, for examples 

Board, Kim 0», 6502 Processor St, Santa Clara, CA 95050 
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<~ ■ z ~ ^ ; ; ~ " ' " " "" t 

.." . . . _/ s . ■ _ ■ . .. . - • J, 

The FIND program to do this is already on your PROMAL Demo Diskette, To 
see the source program, type; 

<;>IT FIND.S 

The ESiTCL - ^ ' P! sl*r cr"% load the file. into ro;=^c :y , ano then display the 
first 2G lioes c: the ;:cgram» The enz :.. "*e zsxt z : the program is reproduced on 
:hs frill" irir :rr ~ f c r ~ : .ivenience . 

JLfcer the Ci^ct lias, yc ~ rll! ~ c tire : nal there srs a nur.b sr c " 1' «es 
which start v.n rh a semicolon ( w <• These are comments c . Any line .-;nich starts 
with ffe: ' is ? comment . Cor»pletsly b lack 1 ires ere cors ccered ce-m^r "~ c: 
You car rise rut a " aid a c carers ot £t the errj g: a, s tament . It is rrrs:f» 
ered gocc c^cgramming p~ac t ice to put enough comirer- rs ir your program tc 
adequate ~ ; document _„c I": - c irpcrcact to realize <rhat because PROLYL 
compiles yjri program adrirg couiraer. ts rill rot make your program use any more 
memory or execute slower. The compiler simply ignores all comment lines « This 
is an important difference from BASIC, where c crimen ts eat up valuable memory 
and in.crea.So execution time. Naturally adding comments to your source files 
vjili make them bigger , but this has no relation to the si^e of your executable 
reject program. So feel free to ccrrrer r : 

Hold down the "cursor down 11 key arc toe EDITOR will j scrcll*~ the text 
upward till you reach the end -of /re program. You can use the "cursor up" 
key to back .up in the same way c Now scroll the screen until the line 

INCLUDE LIBRARY 

is on the top lire of the display. 

how ie ; ~ * s take a look at this program = Do n ' t expect to understand all of 
It afcer this explanation ; you just want to get the general idea of what a 
PROMAL program looks like and what some of the main concepts are o You'll need 
to study the PROMAL LANGUAGE MANUAL before you will actually be able to write 
or fully under s tand a complete program c 
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; '-ill .iicpl^T sll i:i£S I2 ;:e file MYBATA.T which contain >;ie 



; FIND 11 New Jersey 11 MAILLIST. T > TEMP • T 

; will output ell lines with Mew Jersey co :ae jJiie ..EMPo i irom i<*a ll^IST. T. 

; (quotes are needed if the string soug:: t „ ~ cl r 1:5 rianks} c 

INCLUDE LIBRARY 



FUNG BYTE HASSTRING ; STRING 

; Returns true if LINE contains the desired STRING 
ARG WORD STRING ;desired string 



BEGIN 
1=0 

WHILE I < LENSTR( LINE) 

IF CMPSTR( STRING, "=" , LINi->I ? TRUE, LENSTR( STRING) ) 
RETURN TRUE 

RETURN FALSE 
END 

BEGIN ; main program. 

IF NCARG <> 2 ; wrong # of arguments? 

PUT NL, 11 FIND errors 2 argSo needed. 11 
PUT NL, 11 Usage : FIND string cile" 

ABORT 

INFILE=OPEN(CARG[2] ) ; open data file 
IF INFILE=0 ;open error? 

PUT NL, "FIND errors cant open 11 ,CARG[2] 

ABORT 

WHILE GETLF( INFIL£ ? LINE) ; read a line 
IF HASSTRING( CARG[ 1] ) ; string match? 
PUTF STDOUT, LINE , NL \ yes, show 
END |thats all folks 1 



BYTE LINE! 81] 
WORD 1NFILE 



I Input/ output hrffer 
1 1 .it file hand 1 e 



WORD 1 



; index to line 
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First we need a few rules; 




PROMAL supocr : z S e f^I losing data types; 



BYTEs a single cna^rac-e- . or an unsigned number from to 255 • 
WORDs an unsigned number from G . C3 ; 5Si, _:cen used as an address, 
INTEGERS a signed whole number be twee 3'- ,5} arc- 

REALs a "floating point"' (decimal) number between -1 •OE-3 7 and +1 .OE+37. 

4» Key words and variables must be separated from each other by blanks. 
They cc* ' " be ~rn - cge t*~ e : in BAvir. = 

5 • lu^r suline'" a -£ gi ren names v -^c =~ line numbers) f and can be either 
PROCed ~ r is c - JU'CiO s r- f unc 1 " ct s.arts with the key word FUNC, and returns 

a v e - € te the 1 v..g - :q -em -.en li-e BASIC), The function definition 
CcLs rbe cype of d a t ?. t r- e function • e^rns. Procedures start with PROG and do 
roc return a value* They ere similar rn BASIC subroutines • Both procedures 
sud functions sre called cy just putting the name in a statement • Func t ions 
and Procedures must be defined before chey are called. In PROMAL, therefore, 
the main program 1 1 --ays tones 1 a - t ; af sr all f unc t ions and subrout ines . 

With these rules in mind « lee'e _col* at few lines of the program; 

BY^S L^gfg;. 1 ; Input/output buffer 

WO*i* i£^'lL£ ; Input file handle 

These two lines ce f ine two variables used by the program ♦ The first variable 
is called LINE, and is of type BYTE* It is declared to have a dimension or gj • 
This variable will be used to hold a line of text read from the data file < up 
to 80 characters long . Note that FR.GMAL, unlike BASIC, does not have a 
primitive STRING data type o Instead 5 strings are treated as an array of uftes . 
This may seem like a shortcoming at first s but you will soon discover that 
PROMAL can actually manipulate strings very easily and much more efficiently 
than BASIC (experts in BASIC take note = this is because PROMAL never needs 
time-consuming "garbage collection" ; o By convention, a PROMAL string is an 
array of bytes terminated by a byte ( which is why LINE is dimensioned 81 to 
hold up to 80 characters) • 

IMF1LE is declared tc be a variable of type WORD, Note chat you still have 
to declare i t ? even though it is not an array e The comment says that INFILE is 
a ?: f ile handle 55 . A file Handle is a variable that is used to represent an 
active file c We'll demonstrate this Iater e 

Now study the 13 lines beginning with; 
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MEET PI 



mess i % i mes cie t me a. tunc c ion C3 i led HAbbXKlNG* xne tunc c ion encis with cne 

1 ; '.• Irr: . J" 1 " .. . " or : j ;. i or _ '-• -7 -: ' :.. "■ i ~ •: ~: : - ■ \~ zb r - r . : . e • • r •-. ; o*. _ ,* 

" r ' - ii'£- h. ? ^ 0. -A 1 - ~ ■\'.c , ::\- ' ~ - r - - a rry n cr» j ..• r o r v ; *: i. s i r ; £ - ? ~ c c 

ARG WORD STRING ; : : . ... string 

telle u. r th^ I r:;e t v_r_ will expect one argument (ARG stan : « : "*^r "argu- 
ment 11 ), _ :c It rill re : 5 type WORD and will be given the nam"- HUNG inside 
this f L.-i./, j L -„ :. 

If 5-„£IC is the only language you've ever used; this nexc par: may be £ 
little bard co grasp, so don 7 t be concerned if you dorr I ger. it c Actually r the 
variable STEI-G -fi!l hold the sMres? cf fchate-zer string the calling rortirre 
passes cc :t If faction HAS STRING ia eaiiac lihes 

I-i h. S S T R I N G ( n C A 95050") 

th^r e STRING ' r r rieble will hold the address of a string cf bytes in memory 
coat? iriing 11 CA 95050'% terminated by a zero byte . This whole string can be 
manipulated using the STRING variable. 

The lin.es 

WORD I 

declares a working variable for use within the func t ion o Because this variable 
and STRUG are both declared within the HAS STRING fur:c;.icr ; they are called 
local variables and only have . meaning within the func t ion c You may define 
other variables with the same names in other subroutines which would be 
completely different c This is an important concept. You may define and use 
variables ic & sub rev t in.e ^ "hr ct hav ir,g to worry if you have already used the 
name for scene thing different elsewhere c Var iaoles declared before the first 
subroutine (such as LINE and INFILE) are global end may be used by all subrou- 
tines 

The BEGIN line starts the "action 11 part of the function* The next liaes 
1=0 

will be the tirst statement executed when function HASSTRING is calledc It 
sets 1 to 0. This is an assignment statement, just like BASIC* Mote chat 
variables are not automatically initialized to f as in BASIC, but contain 
"garbage 11 until you assign something to them. 

Now let '* s take a look at the rest of the function de fill rice 2 

WHILE I < LENSTR( LINE) 

IF CMPSTR( STRING, f, = fi , LINE* I ? TRUE, LENSTR( STRING) ) 
RETURN TRUE 

1-1*1 
RETURN FALSE 
END 
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the display, t tie 

zz.ziozz u .ir-" c_ \ nc r-~ii- _ :cr, ;:: . •. ' . • :c 15 -l£~ ricsltiE . . - r~ 

The WHILE statement is one r ~ several kinds of Icorc in ? ROMAL • It has no 
direct counterpart in B^c 1 1 , lut is something like £ ccF.binetion IF and 
FOR-NEXT loop. A WHILE loop has the forms 

WHILE condition 
statement I 
statement 2 

m m m 

rert 3 -I? cerent 

A WHXLS statement : e 3 • . & c-«e corciticn .lira a BASIC- If s tatemerc) , If tre 
— rll:ier is TRUE :rar. r ' 1 -nden-sd = :a:enients . c :c cement 1, ccs consent 

ce-,; £re executed c nf ter tee Inst I idented s tatemeni: C - ^ - v Is exec r led c 
control passes back co ere cop of :he loop acid the condition is tes tec again. 
This Is repeated un ; i 1 the condition Is false * Centre I then passes directly to 
the next ( non -i nd e c t e I to teicent z 

re- ■ yc . zhy see nV. ?L3nAL dees r.c c need statement numbers rrrie atructure 
rf r F^M^k. program is gi^etr by its indentation. By the way r i; is vary easy 

~o generate indented Lines rith the EDITOR. The TAB key (or CTRL- 1 } no^as the 
margin I:, by one level el Indentation i zzio spaces) ? and CTRL-i { AppT z] or 
CTRL-U (Commodore) mo^es It back cut o 

In our case i: the WHILE rests cz see if I re riss tree the length ci the 
current lire cf Interest. LliLk LENSTR is n b Ic-i - LIBRARY func :ii:i which 

returns the lergch - f ~ seeing P much like the 3.-SIC fraction LEN. 

Another built-in library function Is CMPSTR, which is used in the next 
line : 

IF CMPSTR( STRING, "=" , LINE+I, TRUE* LEMSTR( STRING) ) 

CMPSTR conpares It;o strings c It has the following forms 

CMPSTR; s tr ing 1 , operate r , s t r ing£ 5 fold , 1 liri t ) 

Here string! £.nd strlng2 are the addresses cf the two strings to be compared, 
and operctcr is the kind cf comp&riscn deslred r chosen from 2 

11/11 51/ _!l fl/vll it ft flv_fl f t v 1 1 
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"« s - ~~ ' - • '6 r " - 3 " € ~ ~ . ~ - \ - - a -r l : ' . O ■ 5 1 = . ~ S, c - ,i„ 1 ' .. . L ^ J ~> ^ \ 

cno i if- enei 5 : ri € r^n : = v i ~ " : ^- t-r-:~ *~ ' ~ ~ '2'f V" -*: • t: :i c 

B ' 1 / " _ ^i:r^rt - 

17 -reives - : 5 LEN(STR:.:^i-; . rrS5~ ^ 

except chao -: rere it nc :rc-isicn in f^SI'~ tor tre^ti^g equivalent upper and 
lower : a^e le~ ;e~~ ^ -qjai 001103 3 i t - ' r e oc-^psrioir, 

If car comparison Is crue , then the aesirec scrirg (for example « "CA 
-'I-C^^'* liss hear 2o r.-c s one where in the lias, zz 

RETURN TRUE 

is executed, which exits from the function and returns the value TRUE to the 
calling routine • In PROMAL, FALSI is rsfired as . a byte with the value Z t £nd 
TRUE is 1. 

If ire desired string is act found then; 
7=1+1 

is executed. ~:hich advances to the rext character o f : :he lire r and the WHILE 
loop is repeated* If the desired string is rot fcurd ar,\imere in the line, 
then ccncrol falls out of the kHI^E lore \izc 

RETURN FALSE 

which simply exits back to the caller with the value FALSE returned = Therefore 
our function, will return TRUE if LINE contains the string passed to it and 
FALSE if ic doesrr to 

Again; if some of this discussion seems unc leer : don't ^orry • We are 
covering a lot of ground very fast sr.d super f ic iaily f to try and give you "the 
big picture" s Keeping this in mind s let's move on to the nain program* 

The main program stares after the last subroutine (there was only one in 

our case), and after the BEGIN. The first four lines are s 

IF NCA1G <> 2 strong # of arguments? 
PUT NL, I? F1MD errors 2 args e needed 
PUT NLc 15 usage ° FIND string file" 

ABORT 

The variable NCARG is a companion to CARG, and is predefined in the 
LIBRARY* It tells the number of command -1 ine arguments passed from the EXECU- 
TIVE to the program. In our case, the FIND program needs two arguments, so we 
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check to see if two ; -.a . s - r:*n when FIND was executed. If not, we print two 
:::or messages and then ABORT. C " r ~ . " ; - - ,.1-ocedure which returns 
control to the EXECUTIVE. 

As siiming NCARG : _ : ; aes above would he 

skipped, and _b a * lii - ^ d c ? -->*r u sc 

INFIL£=OPEN(CARG[ 2] ) 

HIT is an/, tr ar rail ~ in rune -1: i : rn/: opens : :1 1^ Ic a;: _a~ « 1 ' r name ad 
*z~iz ?i) a „ " i'- :r: In r.rr we zz .per, -*d~ ca 1 , lilc ^aiaa 

he ?a^T ?" 5 v^;;t c: Lt < li^ec OPEN . a.. . .> : ~ li 'z~ ~ . r mot 

successful, and the T i ■ a handle 55 athet;£aat ae sccra :^is ""a ad la ;r INFILE. 
From now on, anytime ~-e a r_ t z> access die file, re ";se ccia file hand a o You 
may have multiple files open at once* 

::r 3 . a must, make sure the file was opened successfully* If -:c : . la- 
iusisnce * if the file was net found), we just print an error message and quits 

IF INFILE=0 ;open error? 

PUT NL, "FIND error : can't open ",CARG[2] 
ABORT 

Assuming the OPEN succeeded s - a are now ready to search the file for lines 
containing our strings 

WHILE GETLF( INFILL. Li^E) i read a line 

GETLF is another builfc-i- f;,nr C ion It stands for "GET Line from file fS , The 

firs'C 5 rgument is the file t a ad la and era second argument is tha acdrese waera 
we want tha line in memory * In oar c?ss : >;e will read the line into the 
array LIKE, GETLF returns TRUE if it vas successful and FALSE if ead~of ~f iie 
was encountered before any data cor Id be read. Since we are testing this 
returned value in a KHI T .£ l^op '"he ° rear tad statements after the WHXLS ? -i 11 he- 
repeated until eno-c£~tiIe is reached . These indented lines arei 

IF HASSTRING( CARG[ i ] ) sstring match? 
PUTF STDOUT, LINE, NL ;yes, show 

The IF statement calls our function, HASSTRING, passing It our desired string, 
which Is the first command argument . IF HASSTRING returns TRUE, then the line 
contains the desired string and we should print it « 

PUTF is another built-in procedure :*hich is very similar to PUT. The only 
difference is that PUTF can output to a f ile 5 not just to trie screen, like PUT. 
The first argument of PUTF is the file handle to write to o The remaining 
arguments are the same as for ?UT 

Why do we want to use PUTF Instead of PUT, and what is STDOUT? Well, we 
could have just used 2 

PUT LINE, NL ;yes , show 
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STDOTv - -.-randarD OUTput) . 

opened to the screen, 
he printer or to a file. 



— > FIND if CA 9:Zzz : " MAILLIST.T >3 

This would redirec L ell che c-.cu: do u-ie pi:c:e, ( ~' 1 { - is .he name of the 
printer in PROMAL) . Thie Z/C red tree ie- is eore £^csn?:l:a„: c by the EXECU- 

T1¥E# All your program tss to do is c^iu" c S™I>Ci { ~h £rd the output T ~il ; §c 
wherever the command line redirects ic~, I iz 4V L .^vc^ct'" to oper thit ii'^, 
because the EXECUTIVE has already done it? The ;5 > Si is c.le output redirection 
o-r^c: -^-P the EXECUTIVE and shcr 1c 1 r • .1 rre I^su eic^artc For example; 

— -> find "cj, ssc:: ,f iiailiist.t > callist.t 

would eutout the lisc zz lires to z file crllef CALLIST.T 

This completes oul c is cuss ion c r the FIND sample program. If yor want to 
try r.he FlrlD program ? yc-~ ^ar 4 exit the editor ifH key followed by Q 2nd 
<RE7URN>) ? and then execute it froir the EXECUTIVE, You don't hare tc compile 
it because the object file FIwDtC is already prcvioed (but you can If you want 
te) 3 Since you don't actually he -a a mailing list on disk to cry it or, r you 
mlghc want to c 1 y rhis exempt e Irb cead : 

FIND "WHILE 11 FIND.S 

Whei" dees thr s do? 

If ycu'' d like to try out the I/O redirection feature, hut don' t have a 
printer 5 try this % 

FIND ls NL ff FIND.S >W 

TYPE W 

This ifill i-rrite all lines containing NL in the file FINBoS to the Workspace 
(deleting whatever was there before)* The TYPE command will display the 
contents of the workspace on the screen . If you find the I/O redirection 
interesting, you might want to try this too; 

DUMP 1100 iiSC >W 

TYPE W 

What does this tell you about the built-in EXECUTIVE commands? 

if you have persisted this far . you will have little difficulty learning to 
program your own applications in PROMAL^ So far f you have learned how to EDIT 
and COMPILE a PEOMAL program for handling text files • 
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-ROMAL real arithme-'-i^ * - - zcwt ~e *"e ! j ri" ; i^nt -^i?* 7 ^:=^-?e,£ of 
nl; : like BASIC* 

r i .~ fri'.i sely „ r-.cify the output format f : ?_ JH> 1. rs^l ( " z r 

example, he- _~£ny decimal r 1 r c e s you wish to use) . 7~ i : lr. very impor t&ne for 
bus i zap o s z r * 5 .; ... , whe "e decimal point alignment is impacted; 

3 ASIC- juIFuT 1 ROMAL OUTPUT 

$100 

23.21 

.6.66666667 
Hoi 



140 "6:3t~ 140.98 

3^ FLORAL re?- 1 arith-s : i z i? usually zeszbz "ha; 1^3i r \~ z z not nearly so 
fast c.s arithmetic on BITE, UGFlj or INT caU types} c 

4* The PROMaL LIBRARY does not include builc-in functions for square root, 
trig functions, exponentials ? log functions, etc c Instead, these functions are 
provided in source hrm which you can inc lice ££sii;; in your programs as 
needed - IPPENDIZ 11 describee these functions, 

- hllitzLM BUSINESS ^^LjJ^ji 

^ simple program osl^ei BUDGET, illustrating the use of RE-H ciszz ic 
included on the PRCh^L lishette . To run the BUDGET program, c>pes 

BUDGET 

from the EXECUTIVE, This program displays a hypothetical budget report showing 
expenditures for a month. You can study the source file* BUDGET- S ; ^ith the 
EDITOR to see how to format REAL -ui^eric output « lie won't cover this program 
here, but the file BUDGETDOC.T is a text file ^hich describes cue program. The 
P ROMAL LANGUAGE MANUAL provides full inf crm£ ti on cn REAL dscso 

AM ADVANCED PSOSMI5 

Have you ever wondered how BASIC, P ROMAL, cr any language evaluates an 
arbitrary arithmetic expression with variables; constants, parentheses and 
operators? If so s you may have imagined that I c takes a very complex program 
to do so o We 1 1 « the file CALC.S on your Demo disk contains a PROMAL program of 
about 180 lines (excluding comments) which simulates a four-function calculator 
with 26 "memories"- This program can evaluate any arithmetic expression of 
arbitrary complexity s using the four operators + , *, and / plus paren- 
theses^ To try the program, types 



01 



is * n 
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>wing two - ""2 1 r - c r " the decimal pr ~ ~> ~ 



3.32 

You r^y ilsc type an assignment stateme.v; tc cie of the 26 variables, A through 
Z. for examples 

7 - 3-14 
x = 2*p 

Yce ma; also cr.ange the numbs:: o £ eecissl pl£"es crsp^syea for answers. To 
change £0 I decimal places, j s z 

#6 

When you have finished enper Iran :I"-g *~i G^LG f you c^n e^i; b£C 
EXECUTIVE by just pressing <LSTURi 7 > by itself c 'xck let's t£lce 5 
program. Having a good-s ized prograr "'ill give us a c^anoe co t 
the more advanced eci>: lag features of FRGMAL, too. 

ADVANCED EDITGH 2Z^TCm% 

From the EXECUTIVE, type; 

UNLOAD 
11 IT CALC.S 

This will unload the programs we now ha- e :: r^mory and EDIT the source program 
for our four-function calculator. rlrst. ■ lee's zio all :r:e way down to the 
main program. Press the 15 function key* The ucra Sim will appear in the 
status area below the working display a>r aa • Complete the FIND command like 
this s 

FIND 'MAIN' 

and press RETURN* Be sure to remember the quotes (either 11 or ' will work, as 

long as they're che same on both ends of the string}* The screen will almost 
instantly change to show the 20 lines beginning with % 

BEGIN 1 Main Program 

The status line will sho«v thaz tr.is is line 2L^ m The cursor will be on the M 
in Main« This is hex*; the FIND command worKs • You can also search for a 
particular line by specifying the line number instead of the quoted string* 
For example s FIND i will put you back at the top of the program, and FIND 9999 
will put you at the end of the program (because there are less than 9999 



Iocs a; ttris 
r y ot: soma of 
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dsfir.5.- ,'1:/.. . r.\..t LIjESI : : hi' -e chs value 80 through: ut the program. A 

cong tsr r i c ~ *r € ^£r: : ^le : t v - cannot have its r^lue changed during 

c^ec-oic Z - 1 c the ic^vCatCc -::s declarations for se ; variables . Press 

21!1L-=2I tc ac\:£icr cr taie ie^i server: sr&rtirkg with line 41} 9 Notice the lines 

REAL VAR[27[ ; facial les A-Z cur value 

rh:c Errs.}' ci type REAL will _iold the current value for each si oar simulated 

' s "-Leiiiories 11 • Suppose you decide you want to change the variable 
'l j .l re ce e~lied MEMS ins te&d , throughout the program. Use the F5 function 
key , a ad c otr.;. le tc t he o r-nms. r t d £ s : :; 1 , cws : 

CHANGE 1C§ ' -''151 "111MS~ 

and press RETURN This ceils che EDITOR to change ICO occurrences of ¥AE tc 
MEMS* You will see the first occurrence of VAR highlighted { in a comment.,- arA 
the status arei shew the prompt; 

CHANGE THIS STRING ( Y/ N/ OCANCEL) ? 

You car, 7 r ess Y tc change the string and advance co the nest occcrrsrxs ? 1% to 
advance cc the r t exc occurrence -richcut changing this one, or C to cancel die 
command £t this point Pre ^3 ^ £rd watch west happens. The ^S;:t* c .i^ur re -ice is 
oigci^gr cea ; «aa you -1 r a egc :_r 5 s ice a it you want to change i**~ Ho^e - r er > this 
occurrence cf 7AZ occurs in toe vord VARIABLES in a commen; 5 sc you cor, c //ant 
to change it- This is r^y ^ ~u gez a chspca ic ,; ?eto fl each occurrence! 
Otherwise you night get some surprises Press IC to skip this occurrence. 
CoTiitinoe pres=»iag Y or 1 at each prompt , as appropriate (most will be 1). When 
all occurrences have beer, found ar t a presented to you, the status area will 
shows 

II CHANGES MADE. PRESS RETURN. 

to indicate the total number of changes made out of the 100 you specified. 
Press <RETURN>c Mow press F5 co issue a FISD 72 command . You should see a 
DATA statement: that locks similar cos 
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v r : •: s 1 ;'^: - .r Go „ ;1 c . c • . d - - 

Ihis dc-JI-.. siscerrerr;: derlaie: sr. err^; f :f •; i, ... e c HE r' : . 

-i ta zeniaz-z- are £Ginscr = s : ; lire Z^SII rt-. dr -^".er.'.r.s e--r e : : r. e° 
:c ?rA£ :he datr ircc e c^rirbde- : "? already ' he : e pAl> ^tei ^ei- .. s - - e t"-- : 

Galy s «;a cedents crac -zaj ":el<e r.r iliZzzzlB direct dr.. a brackets £::~r :r s 

cha brae'-'ecs fcr £ dadla cs: lar e r do r, ceocrse ??rChAl r :d' 1 figure eat he 5 -" rrg 
There do - s If ve late~ rave a s Utemerr < 

pot b^oro] 

it wr ; " c! sticv; 

ai ass igniter t statement to A through Z 

if you have a Commodore 64 instead of an Apple, the lf \0F" and fi \0E ,f in the DATA 
statements will be replaced by 212 arc g 12 The Co rare do re does not have a 
backslash key, so the "pouncs e .:er ling" ^e* is rser ire r e~d . The \ or £ symbol 
is used in a strirg to embee ncn-o -in le ciarcCte:Sc The \ is followed 
b; exactly two hexadecimal digits '.rice g j. ere cade fcr the desired embedce - 
cortrci character. In this rase, ids \ Cd' arc \ Cd ':r:r. ~: i"erse video on and o^f 
r^s-^cr i-*ely on the Apple (arid ill crd d-12 d: "he :£cc d miction on the Comme- 
rce e - r ^>d ~ 

doce chsc era rirray HELP is declared to have e tjee z i rdTSIl rather rhan BITE 
?3 yer *r: gh'" hevs e::eec ted . Tri? ie because the rrr?y is erfrelly en - rray of 
pointers to the strings, and each pointer is a !-;erd (this is explained in the 

promal language kamoal) . 

Gertirg back to the EDIT session, suppose you decide that ycr rant :o , c e 
the lines containing the DATA statement fcr the HELP array closer to the rep of 
the pro-gran. r -: bomb reason, Put the cursor or the fir£t line of 'zhe Del,, 
statement (line 73) and press the MARK function key ( 13) . The line will be 
highlighted. Now move the cursor to the last line of the DATA statement ^ lire 
82) and press F3 again. The lines will be shoun in reverse video ; iridicat lag 
they are now "marked 11 for some act ion ? The function key legends in zae scetrs 
now show the choices for what to do with the marked lines s 

i-DELETE 2= 3=MARK 4=WRITE 5=FIND 6^M0¥E 7=C0PY 8=CANCEL 

COPY makes a copy of the marked lines at the new cursor location, WRITE lets 
you write out the marked lines to a file, the printer » or the Workspace • MOVE 
cuts the lines from where they are and inserts them at the cursor location. 
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le , " s ~ r ; c-ie more thing wim the ED I'll rn:lt; liie t;i«i^ The second 1: re 
T7 ill ": sgir ? 7 "4 HE 1:::^ l!c " suppose thai f «: . ?cr„e :ccc:i ;'ou dec lis ; c need 

r,i_ ciS-lc; lre r el rrrd that woci; ercrri~es? si, :na liner -n. :ha 

existing wKlLF Icoo? Th r s neaas that you need tc ifi^eic e ' l ] these line? L ~ 
ci.c J,cr Is'al- Mere"*^ an eas v : e cr r-- - ? ... : t"~ e ■ :rsr - oa the : /:sc 

...ire co be rricentec ( the WHILE 3 :a:sc8 it > end cress ClXEL^ c control key :ri th 
rrift acx ^ * 1" yc : h^ne an A; . 1? ~ : i ** . o*- h^- ? - rc-jredore 6- ~ T~c 

lice jumps to the rig?/; ly twc sp-ce^o rrsa: trie - iir re,~ igsin and "he zszzz 
line will indent . Just rep sr. t his :; ^ sr rrry tire? <= s resi -^i. To get ri? 
r j in unwanted level zc indent - -i.c* :r . o 1 ILL- _ :he l-iier C~ ~ If 
forget what control keys do w *. ? r . nse :rs hi J.? rr c i - L~y .1 7 ' • 

You've now seen mc s : c :: the ma:c£ iertrres o: the EDITOR* If you wish you 
may study the rest, c I z :> e program he fere exiting lack to the EXECOi i l - £.„ The 
comments should give yen an idea »-hat is going o r - An imports r.t -rcer me is 
procedure LTrTOXLN, Trie re re me reefs Ltrrec^e a lien the Ir „e ...•/;. , r 1 x. .,. has a 
complete "token" . A tcrer is r rcrrple::^ rrnteic h. ""variable rsire : cr er 
operator « hher. rmriri rg this routine, it rill .... r helpful to know that the 
PROMAL operator §< is caller en indirecc ere re ccr 1: reliefs a vrn?: le rene 
chet 9 - hei^g -sad £S - ^ e J LPTPjc ; rher^frrr rrt c tie rh-r-etrr ar hrs 
drrress gi-en by LPTF.. PrrllrrL r upper ts rlher irr irsr 1 crsrrtcrs ar ^rell rr„r 
can rerrcrm very powe : 1' 1 : cs;r ~. ions ce irg tc:iC3'~3r 

This routine uses several new f unr ziot..? car ire: ir, : ' e LIBRARY. The 
standard function TOUPPER converts lower case chararters tc upper r £ s e c. The 
standard function INSET determines lea. charade, is in a scring sec c L 
characters. The function NUMEllf as as if a -hfie - ter is € name J ir rrglc- The 
function STRREAL converts e srrirrg to s resi ralre ( s one what like -:re BASIC 
function VAL) • All these functions zre cetsi: ed ir the PROMAL LIBRARY HMIU^L, 

The actual parsing cf the input tc C^LO is dene by a techrirre Ivno^n as 
"recursive descent" • This is e gcal-crienced technique which tries -;c match 
t'aa input line to a knom pet ^ern ? where each part cf the partem is processed 
by a subroutine. The theory Involved : s fairly advanced, and there is no need 
for yon to understand ° t o if yon are interested you can relic:* 7 through how the 
CALC program processes a sexpie express ion "by hand" , which v;il 1 be very 
instructive to understanding i t ♦ Also, Appendix ? cf the PROMAL LANGUAGE 
MANUAL has some further discussion of recursive descent parsing and syntax 
diagrams • This will only be of interest co the very advanced programmer , 
however. Our main purpose in examining this program is to show how to use the 
advanced editor features, and introduce some new statements. Also, we wanted 
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COMPILE CALC 

The COMPILE! -1 ~. -< : c . il ;z _ v- : — ^1. ^ rhr err ^ J -i ^.L., ; i:.'. - 

' : c r i. s L : ■ „: i . - ™^-: " ^1/i^r Y i 1 ? ri- 5 -:"." -""ill ce ... lire 

because r-./ ::. . - - • e : ; lr- cne program. 

For ac -&r - pr~ r a =jv srs » lere are some adc -ii~~al cap^ 1 .1 » - ^ which 

may be icporlart ;-rv- . These are de-rrired ir Ibe PROMAL Lit^TJAGE MANUALS 

1. You can assign the address ci an external variable ary-rrere In r:emory . 

TLia £llo;#s yo_ ii riie ne^rirgf^l r^mes to those "speci&l f: $ddre?r-e? For 
example :a an Apple sys tern you might uses 

EXT BYTE HIRES__ON AT $0,5 7 

whirr rssigns the name HIRES ON to th- Apple Softswitch ccrlrc 1 ling hi-res 

graphics- The statement HIRES 01:1-1 xl 11 ::.ere fore enable h i ~r e s mode • A 

Comrrccere 54 example would bet 

Cvu 1£^0M=7 

EXT BYTE BACKGROUND AT $D021 
• • • 

BACKGROUi ^ .,0W 

This sequence laic per. 3,1-/1 1 ;„err„rgr _1 ~£r_s ir 1 re .kg round color 

reglsler and maoip^ia-s 11 lika £~p 1 Irer rari£:ls l5:LL: 1 ..-XKG ROUND= YELLOW 

much clearer than its BASIC p:u:vi1sii cf Prill 55281.": 

2 . You can perform hic-level c per a : lens ^irh riGHAL »ec-~ as AND, OR, 
EXCLUSIVE OR, and SHIFTS * This ofie- eli^i^eces the neec far machine language 
programming for Z-Z r c special needs. 

3 • If yoe ar d: need machine language routines, PROMAL provides a clean 
irierfrcso Icr i£r ^rll nacrine language routines from PROMAL with passed 
argument ^ y), ,„. au ever, set the hardware registers if you rant) , You can 
Sfi.t e t rscAir.e " u^ge ro a lines in DATA s Is zemer.es ; ox iced larger programs 
1 rri: lisle rs Lng a built-in libiary function,, or directly from the EXECUTIVE. 

BZZKE rrl.ILrL BrS^Mr^SKlBIl^ SEMO PROGRAMS 

Your PROMAL Dero d i s r has some other demonstration programs which exploit 

che special capaoiii cies of 3 our computer • You may wish to try these programs, 

which are describee briefly below. 
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e. zz; zzz":^ zzzzl raccrc :r~ = ?eca 1 '' a Slercrd Sk:? V; reej>£ e d£t£be.re *"' 

creation abcuc elbciLS ere in cioc'^ : .1 disk; The records ere rept as 



c re i:„ar v secuen^is.', rer.' tr-ie^c '-~ith ee?^ r - r% -. - - ^ 



. £~ v",p 1 - - 1 ' 



e 1 c;mc; : s r r ~ 



I Artist rere : lri,5'z} \ Liz rr: reme " Label - Tear j Qr&rcioy 1 is in ?r 



For e>cesple ? a topical rsccrc from ~he database file Icgks like this 2 

Jackson Michael Thriller Epic 82 0040 0IC8 

Hie ..esc :tce cclccis tell ere c.:r :, ::h:/ or. hare and the bin r,umber , which is the 
pny s lc£ 1 lecerio: of .;he cltrrrs ir* the store c 

A smell segment of this hypothetical database :s the file RECORDDATA.T on 

£ ~- <r» ^ o~y» ^ -~ - ^ "' r r ^ 3 1 "h ^ t r *^ — — s~ ^ 1 ~ ^ ~ " " g j 

rT?l RECORDD£T&»>: 

The SORTDEMO program lets yon sort this database by any of the fields, ir 
ascending or descending order. Types 

SORTDEMO 

from the EXECUTIVE and you should sees 

PETE PROMAL' S RECORD SHOP 



SORT UTILITY 

Please select the sort options below, 

<space> changes the highlighted option. 
<RSTURN> accepts the highlighted option. 
<ESC> exits the program. 

Sort order is [ASCENDING] 
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: z 1 1 r a c z t n e c c,:? f i 1 z t 
lay the records in sorted 



sort 



"*= "1^1 " z z z: . *-er . '* i s ~ : _ :ce ::- 1-: f_r %~ ~s ;x ~grar. - if you wish to 
? z zip 1 t : tze reverts r;ll help zriplz iz. the zzarztzor z : : ~ 3 program • 

FgE TUB C ggjgCB Q&E 6^,,_0gLYg 

Ir.s zz L < z T * T iZti2 s^ecici az^lizz « 1 e Coi^ccic ~z, e If you don' t have ,a 

Zorrmodore 64 f jog *nay wish co skip do^n to t;ze section, " IN CONCLUSION" . 

Sfll^lSp MUmkTJME? Aim SCUHB SYNTHESIS £1T£ FiiCiiHL 

On zhe Gcirztocora 5-: ?*0 7 rL<i lisnette - r,ec erazaly zoriipler program cai^zd 
5 IIL~ARD3 o 7b is illustrates he? rPXiiAl ^ai be used tc program sprites and 
sound in real time* Although the pzcg ~z:u is net a czxzzzete gaxe prcgrao, i z 
could be upgraded to be one The orogran -^a s deliberately chosen because it 
involves a lot of computation , s great deal sore than nost animated games c The 
program, simulates the motion o f tnrse bails on a billiard table. It actually 
approximates the true behavior of che balls by the pnysioal equations of 
motion . It solves collisions between balls and the rails using transfer of 
moment 111,1. and includes coefficients c z drag sc the; bslls eppear to s lev dzrn 
realistically * We ' re not saying ycr have to te a physicist to use PROMaLs but 
rather ? that if you do need to do something complex, PROMAL can handle it a let 
tetter chaa BASIC* 

If yen zr ice Zeis program zti bASbb- trie re simply won't be any animacicn co 
speak of ; because the bails rill move slowly and jerkily. With PROMAL ? the 
balls bound around the table fairly realistically, complete with sound effects = 
Ins Dilliaras program has already oeen compiled for you on the PROMAL Diskette G 
To try it from cne EXECUTIVE, types 

UHLQAD 

BILLIARDS 

After the program loads, you will see the table and three bails o One of 
the balls will zip diagonally across the taDle, colliding with the others. 
When the balls almost stop, the program exits back co the EXECUTIVE. Yon can 
use CTRL-B if you want to run it again. After you've learned more about 
PROMAL, you might like to modify this program to accept different angles and 
velocities for the "hit 11 on the cue balle Or f if the balls on the screen look 
egg-shaped instead of round (due to the fact that pixels are not the same width 
as their height) ? you may want to change the sprite data to make the balls look 
more round. 
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We won't go over the source program for BILLIARDS, but you may examine it 
with the EDITOR if you wish. -.1 the ugh the comments - , si;--- ^11 - ri . i idea 
what is going on, you will need to study the PEOMAL LANGUAGE MANUAL to fully 
understand tl cn?L.; il this program ♦ 

If you liked the BILLIARDS program- ;i" rhis : 

UNLOAD 

INFILT?* 

This r: = ".c: i iafily : m: le - ;cr. - :yi j£i=i veil ten milady iv 

PROMAL. TVs ^i::ie -de lo thz s progrci: include- ci ore of the PluMA! 

disks, if you'd ii-.s .: .1 exsnire :r imp re us it- Thic gane feaoire^ s^c-cch 

horizontal ^~~-oArl::g ' Lryo? -i hie " a on ZttSZZ[> ; 3 'leipje nvi 1 i - v 1 * z c z~~~~ze<i } >nd 
some "phase :* r end s^ilc«icu accic c ::8;;s c lli^e fun I 

Note; Because :bis orcgrar/s source fiis is larger Lian 40C lines, you 
will cot h 1 able to civpila it vitn the Ze^c coupilerc The standard ccispiler 
can compile i c e&silv ^itn me B optiorio In is program uses an INCLUDE file ? 

il? 21;llCLUliei 

As ui ssid Si:; 1 1 . '. ; .ha purpose cf this man„il "'£3 not 11 oaeeh you how to 
program in PROMAL but to give you a good idea acouc tvhat i ': is like zo program 
in PROMAL* Yon have now gone through the mechanics cf ed Icing ? compiling and 
running small and large programs o You have used a fe-y EXECUTIVE commands and 
know how the EXECUTIVE can run p^ oghams and pass command arguments to programs. 
We hope you now have a good idea of what PROMAL is ail about. 

There are many powerful PROMAL lea tares we have not even touched on yaz c 
For example 5. you can use the EDITOR to prepare a Et 'script !i of commands for the 
EXECUTIVE to execute using the JOB command* This can be used to run a whole 
aeries of crograms or commands as £ 8S b&tchUo Also, we have only seen a very 
lei- j L whti rout ii_e» la the LIBRARY* There si e ^ny routines in ic ■; o ac 
s jer yching from a t lock-move tc seai ch: ug e linked liste 

The PROMAL LANGUAGE MANUAL contains a full expianst ieu of hew to program in 
PROMAL, with plenty of examples provided* The LI3RARY uas a reference manual 
of its own. The PROMAL USER'S GUIDE explains all the built-in EXECUTIVE 
commands in detail , as well as all EDITOR commands ana compile*: options. If 
you've liked what you've seen of ?ROMAL 5 but don' t quite understand everything 
we've covered , you'* 11 still have very little difficulty becoming a proficient 
PROMAL programmer c 

MAKING WORKING DISKS 

To start using PROMAL for writing your own programs 7 you will want to make a 
"working distc" with just the files you need on it plus your own programs* 
Append in tells you what files you need and how to copy them® 
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TIL: :. r'-ilr---: 7 - - - _ i. ^ ,~ z ~r "End User 11 

r c > : 7 * : o z i r i ~7r l _g = -c.^- ' : . ._0 7 p _ ^ * - T:- j r " - on your 

~- ~z' o-:- = _ ;--:-.M-=- _ :n_-:_^.c > J- - 1- , liaHl The 

: _ : . ; e *' * r c 7 c _ ; - " - 7 e - " * : . • -"' " • - ' .. 1 - L: .77 r ^" 7 " •;_ 7 : 1 7 1 1 

— .77 1:1 71-7711" r;ii:; "i 1 i^z / 7: ^-^ 7. ca:7-r:7i PRlii.-d' 

'.07' = T 7i '~ -"ill " ^- ~ . - : 7.7: , lllr^il. The »s 
"sr:7.:r: Icl;^-: — IV-Jc^c :"r^r-= p-Tr— t~7 . . ff^- :: 7 :!:3 7h^c- 



;V~g^ 7 -7,77:77_ ^y?^:i7 "7 7=7/^^ 7777 . : • 7 C_ ^7 - "c mC_V07" 

^7. .. c>:^; ; . : 7 ILlllll- lixpppppp-p ITU I T r -7- h" 7 purchr-~d '7 

Tnd 7- s r cystsc, ycr 77,7, 1: ::r7cs later 77 7 '7 -7 la-7r"87" - "Greece by just 

payer, s 7 e ::£fc;87:- Lr c-rica \zall 77. retails^ 

TTT1 TTE TlOllTl ^Y?T3S1 

As an option, you can purchase the source code for the P ROMAL EXECUTIVE, 
EDITor , and a source listiug c :: 778 asssobly language Runtime Package and 
Library, This is a unique esuefli cc ? LOMAL programmers, which is not 
available c?r -ry : "ler :o^~3rri- I p — gramming system. Contact SMA for pricing 
and avail a": ilicy 

GSji-Jf £115 T'T GLi IX 

A Graphics Toolbox 77 a a :1 1 h 1 a aa azz c p 1 1 o n c Iris provides very fast, high 
resolution drawing subrcccir-e5 you uar ass from year P ROMAL program. It can be 
used .: h eicner the 1tl6 User cr 3evel.cer '3 --arsicr. cf ? ROMAL. 

Tb :.h 7' 7 li. package : _ car aaall} -Trite crrgrar.s :o drair bar graphic 7 pic 
cl e 77 5 : 1 era 7 7 7n pic ta ar.f 7 the:; graphic images 3 The Graphics Tool': e x rci z- e 

Goimx lore 7 ^ dra.73 iz7 ; 1 colors t.s ing 7hs 321 ey 210 high resolution nor e ~ Zr- 
the 7irpl^r graphics t :e 1 7 r.e 1~ 260 oy 151 7.1gh 7"esc lut ion monochrcic ? sicca 

the iipplc ^-^e c^ 7 h^^a > ' ; g-' -ra? * 1 ' i7~cd<s c Tasp i te substantial cnlerl^ ccg 

iiflsraneac lr„ l=.77 r "?r£^ g7 i 7.pcic« - p ; . c ^ ... -crs 'ccdce-i for ^he Comir^'l v „c -.ca 
highly pc^7£clc 77 zhs 7„7p ^::d ~"iss 
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Call SMA f c * ccder n..g info cnatzzn 7. . ^- /-cos t Graphics Toolbox* 

REGISTERING YOUH PIL^S^L SYSTEM 

After you've opened your sealed System d isket te( s J ? be sare and fill out and 
send in your ;; 5MD USER AGREEMENT, LICENSE ar.d REGISTRATION FORM" o This is the 
omly v:ay you 7 ill be ab 1 e tc get on our mailing list, so you can receive 
important upgrade notices ? product anno uncemer. t s and the ? RGMAL NEWSLETTER. 
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CUSTOMER SEKflCl 



rersic 



- c c •-- - «■ 



Z v. *„ 1 - u £ '. f. . ; . 



'dis^fr'&I?. aiciti?r to your g?f r vsre ccl laetiotu 



#i I' 
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— EXECUTIVE 
— EDITOR 

— COMPILER 

For Af ~ ~~ f ad Commodore 64 Computers 
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_TR0DUCTION 




Hot only do P ROMAL programs rfcer run 10 c : 100 times (or rrrre. raster than 
B AS 1 C j ret :.3r.- trivial programs Ere usually easier to program and maintain in 
P ROMAL rhcr. LlIIC, 



Your r ;X1>L programming syr : r:r ir. rl^le- ell cr "Us roll^nrings 

* c:^:?" 1 ng system EZZ'7tI TT T tz~ let -i- r^ a control 

* A rearer ; rl foil-screen : c gr cc I" 1 1 7 1 ./ £c r preparing programs 

* A fasr- cre-pass COMPILE,:. fc: Ire PnOrlAL : arguage 

k. zcazzsri LIBRARY of over 51 -?crr.arila - r:; c rtiras , ready to use 
ileac y -t r -run demons t rat ic c programs for you to run, study, and modify 

* «. couple re manual with examples to guide you 

Let's take a. quick look at what each c f lipase 7 cols does for you, 

The P ROMAL opera:; lag syrrar 33Ccri7S is yrur r octroi center • You type in 
commands to run programs, aorirate ere PRCnAr.. editor r r cor.piler , and perform 
? ther c pere tiers . A number cf b r 1 1 : -in ccxrarxs ere provided for manipulat leg 
files s cisplaying and chang 1 ng ;-;eircr_ - a^Co „a acdi t icr f you can add your own 
c remands . Ine PROMAL EXECUTIV:: lerr re be - a severs! r --grams in memo - ^ >~ r 
once, and you can run an, cf instantly by rars i> ryring the name or r-e 

program. 

The PROMAL full screen Z'SITOE, makes it easy :o create cr ecaegs rrcgrams c~ 
ran r Information. The ecircr Is like a good word processor 9 except leal it Is 
designed specifically for -miring ? ROMAL programs. To make changes, yen simply 
tt.ovs the cursor around on the screen and insert or delete text as aes Ired The 
editor can scroll forwards or backwards to rapidly display any p a ~ r cr your 
program • Powerful search and replace commands make : : t easy to make correc- 
tions c Yon can "cut and paste" blocks of text ; toe 

The rose Important part of the system is the PROMAL language and compiler c 
The COMPILER takes the program yon created with the EDITOR and converts it cc a 
form. T -hich r ans with nearly the speed of assembled machine lar gcage programs . 

Ir is tcis compilation process which Is mainly respons ic le for PROMAL' s great 

speed c Coop i led PROMAL programs also occupy less memory than ?ASIC or other 
languages • You can save your compiled program on disk* and in can be run at 

any time later by just typing its name* 
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AL 



If h-r a -1 . -Iraa:" _":r_ you should read your MEET PROMAL! manual, 

w 1 1 c 1 '"ill pre ~ice /:u *-ith a ':£::cs-on" guided tour zi cze PROMPT, systerp as a 
v^ol- , Ir— * s srr-: 1 i _ic r ccac as many of the novel ctrca; zz z f 'z % zz 1 H.1HAL 

chid nci^&l, ;;c ??wL^l '3ZZL e SLtfZc "silo „ "izcrr tc use the various 
ccaipcrkeucs cf the P RCHaL systsso ficer ;hcs it:™ ;duc;ici : iz as civicec into 
three rz; - ■ 5£:;iu:,f , co *e ji.ig * 

Opari; cf the EXECUTIVE (incluccrc ell 1XECUTIVE commati-?; ? 
Co 6 r a c i c a z ~. ~, z e EDITOR; 
Opera" ion cf :ha COMPILER, 

The P£Ci-iAL L^HGUAGZ Ma,Kj^h f describes the PROMAL language in aatail= You 

will probably want" tc read it after you have gained some proficiency with the 
EDITOR and EXECjTIvS -y reading the USER'S GUIDE. 

The PROMAL LIBRARY MANUAL provides a detailed reference for the the 
szz zzczlzsz iz rhe LIBRARY, arranged alphabetically . You will want to skim 
this material z f tar reading the LANGUAGE MANUAL, and refer back to it for 
details as the need arises, 

A sec of Appendices serve i s 1 1 z f these manuals, eiving supplemementary 
irrcrniat ion. An index is provided tc ail manuals and the Appenidces • 

If you purchased the Developer".? Package, you will have an add! t icnal 
manual, the DEVELOP! r 5 GUIDE, which covers topics relevant to making 
st and -a lone PROMAL programs which can be rue on systems without P ROMAL . 

s^Miim ns SYSTEM 

The MEET PROMAL! manual ': e 1 1 s you how to "boot up your system 11 using a copy 

of the Demo disk* You snculd always use a "working disk" that has a copy 
of the PROMAL software oa ic s a ad leave the original disk in a safe place • 

Once you have your system booted up, FROMatt rill sign or. aid the EXECUTIVE 

will ncv. display tne default meanings cf the function keys (nctee see tee JOB 
command description below for s ^ T a~, zo defeat the display of che dafauic 
function keys erring boot -up v ; c This display rill look similar to tills ? 
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Ann 1 o T i 

P It JL JL 








po — pP|?l?Ty i 




C"j „» P AMD T T C 1 




F4 = GET 




F5 = FILES 




EXTDIR * 




¥7 = HELP 




F8 = COPY 



function Leys i ? ^ ^li'-di.;^ : :> z^sing in con i^inarc raps ca~ ^ s -~c-~- > T oz 

exairo le r p-es.-ing Jl - 7 i '.. 1 cs";e rhe n c r c ? 'SLIL r to appear on che screen, ;-:st 

as ! : yen typec- \ t m- Ice ,l -=-~v is "nee 7?^0~-lAL prcr:x*~ : cc_lo~~sc by a 

in a command • 



You are now ready cc begin using P ROMAL . 



EXECUTIVE ~CXh^mS AND COMMAND EDITING 



Tc nail the EXECUTIVE something, you can use any of the function keys or 
type in a command that the EXECUTIVE knows. The "built-in 5 ' commands are 
described in detail in the next section. All commands must be terminated by 
the RETURN key . Up until the time yon press the RETURN key , yon can use any of 
the line-editing keys described in Table: I to make corrections. 

Once ycr z .; ess "T T i?^. T r t u e IZICJL1VE nili attempt to execute whatever 
command you have cyoec <- Tr?re are tnree "levels" of commands , which the 

EXECUTIVE searches in this eicerf 



msipe ty 




If the nXnGUi iVi can r i c c find :ne command in any of these places, it will 
cispidy % 



*** ERRORS PROGRAM OR OVERLAY NOT FOUND : xxxx 
™> _ 

Us ei -defined commands are simply compiled PROMAL programs • Several of 

these command files are on the Demo disk* They are easily recognized because 
their names end in 11 . C" , indicating a command fiie e You can create your own 
commands by writing a PROMAL program and compiling it @ To run a PROMAL 
program, you don't have to LOAD it and RUN it like you do with BASIC; you 
simply type its name. The EDITOR and COMPILER sections or this manual and the 
LANGUAGE MANUAL contain all the information yon need to create your own 
commands • 



Commands may be typed in either upper or lower case letters © PROMAL 
operates using upper-and-lower case, like a normal typewriter • If you 
prefer all upper case letters, you can pres s CTRL A, which enables alpha-lock© 
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TABLE 1 



PROMAL LINE-EDITING KEYS 



Commodore Apple 
Key fey 

MTiDhf .H TORN 



Dgj>£t 1 , zpp 



r-ha- r 1 tr ;8 fh 



DEL 



INST 



DELETE 



CZ?I ": 



— > 



Replace the characcsi '.2:: cf xae cursor with a blank 
and back up the cursor one position 

Ena 1 e "insert node". Any ch~ r-= ' : - r ~ - ~ - --quent ly typed 
will be inserted before the cha ' * ~ c er t v -e cursor is on, 
pushing aay existing text to rhe r rer r 5iit :"-ert 
mode by pressing RETURN or otner iir.s =sc i cing keys. 

^slcce character with pullbac" . hriaLri^ ;r e character 
v icier the cursor and pulls any remaining text to the 
i~lc :o fill i"" ■ : r - a gar ,- 

Crrser right . Moves the cursor to the right "ithout 
altering the character under the cursor : , Steps e :. ~re 
end c c "re line. Repeats automat ic a - iy rfrei a :r.e: 

pause if held down. 



Cursor 1-eftc he *es the cursor to t rr 
aitaiiiig the chc rac ter under the cu. se: 
first character entered . Repeats auc?n? 

he Id down. 



hTHL 31 CTRL JL Car_ce_ ths arciir line, Sra^ss rfl chcrr^^r? rr pad on 

tie lira and repositions the carscr tc tha I r r s r 
character pos*-tior. 



CTRL E 



CTRL \ 



_fiaf tc s;^g cr -i-ico 

rrrsrr ro the sec jf 



Erases a 1 ... charge cars from the 
_ le • 



CTRL ¥ CTRL L Jar ? cc last character z £ lira Moves the cursor tc the 

cclur~ !:ar :ha laec charterer 011 the line, without 
&:feccing the lire content 



NOTE : The CTRL key is usee like > srifc hey. CTRL X means you hold down the 
CTRL key and press h ar ths same titrs c N/ A means rc-c available • 



Copyright (G) IS86 SMA fee o 



Bar, C 



CT1 



,pr- -jc. 



efiierca a ad displayed as upper Ca&c wasn typed • 
Does not affect other chars z : :U : «? ,~ed on the screen 

or already typed, ~r c s - ' a a, -aTRL A again returns to 
normal upper and lower case a 1 ~h~? nrde 



Fl Apple 1 Function ke\ =. Erases rurrenc c e n : 

thro ugh thro ugh e a c a j ~ c a e ccn^l^f f un c t i o r. r e y 

F8 Apple S be cyped arte c cne function key ds 

be edited r ^:r c : r : desired. 



- a \ ~i i 



_ — >-I 



an 



C ;5k J CTRL B Backtrack, Erases cu: r e^: rant c - the command line and 

enters ^na .rasr line i 4 „is:ed, ire ;e can be rrypan af:ar 
the reLa 1 lea ::^a:2- .r .: a edited f cr ':aer o 



1 recal" 



next-tc-las; 



Pressing CTRL B again ;;: 
command entered c This can be repeated up to the lirsit 
of the baaktrsck b^ffe^ a f 256 ^ha.acusrs s chen ens 
display i 1 1 :: >/rap around" to repeat the no s t recent 
comma n 



CTRL ST m CTRL RESET 



Program abor:o Uncor_c iticaally aborts the r arrant iy- 
running program and re;: ns ca:::,. ^ the ? kOMAL 
EXECUTIVE; closing say oper -houl ! re used only 

as an "emergency exi t' r . ioas nrr if ; n. ~ rupts are 

disabled o r if a machine-languaa ^ ;/::g:£u. nai executed 
an illegal ape ad a* ... Apple veraici clears acrsen and may 
cauc» a loss c f c a t c in : i la * c pe f a r an 1 1. lug „ 



CTRL 1 CTRL 1 Indicates and of file from the keyboard device if it is 

the firs" character of s line. See the TYPE command for 
an a anlic ~ cion. 



NOTE: The CTRL lay is us ad like a snif t key, CikL X means yc~ acid down the 
CTRL key and prass X at tea same t ime c N/ A means noc available-. 

It is possible to altei a lire s t all rf :ae choice? far editing keys (See 
Appendix G) • The cef aul t keys were chosen so as no: tc conflict i th 
pre-defined Comr.xdore keys c 

for the Commodore 54, CTRL-STOP rrill not be oper ^ . .^nni while the disk is 
being accessed with DYNODISK enabled f because DY NO DISK disables interrupts 
temporarily while it is running* 
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Commodore Apple 
Key Key 



STOP N/A -: .\ ^ :!::- = - -1 . "mr^^ly r - \- \ r~- ^ - t 




aborting programs on the Aprls-. 



CTEL S Pause output. Tempers rx re scrs.s*r r~ cr 

any key Is pressed c 



NOTES The CTRL key is us^. r :, . ^ : key, ■ CTRL X means you hold down the 

CTRL key ari :ra£i :: Sra saxs jirae . M/A means not available • 



BUILT-IN EXECUTIVE COMMANDS 

The EXECUTIVE has a num' r - ~ z ml commands which c.r ^ ^Lra^E ey£H&gLc= 

currrrar ized in Table 2 below* These commands are explained ir detail ir t,he 
"die rmg sections. 
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BUILT-IN EXECUTIVE COtftfAJIlg 





Aval 1* 


_ ~- I, C ~* 


*- LI -5: 


A 














1 _ ; " - „c 


cs 




l_cci :.. .. .. j 


DATE 


II 




DELETE 


AC 


L^lsie £ lilzc 


DISKCMD 


C 


b S CC 1 ~ C: 2. 5 C CHIT'S Til S $ Z C. C C C C 1 a Z SCrCC CCS- Ce~ ""Scl " ^ r 


dump 




lispls> rr & ex : rry ir v ez--1 =s filial £ .ic f^ICH chi^cusrs 


DYNO 


c 


3cdc 1 c ' 1 s £ c 1 1 a c o • .... la -;eec r e f.c f o ° ' J - 1 / = 5 "* 2 z it : . i- e z 


EDIT 


AC 


Enter Che fall seres- PROKAL OlTOi^ 




AC 


Display the namsc c ... h:as : c iisi: f 




AC 


Tel: - rsgirc z J " memory with a constant. 


?EST 


AC 


Rede f ir: i a function key or display present assignments^ 


Sir 


AC 


Load a P ROMAL or machine language program into memory. 




AC 


Execute a machine language program in memory. 


HLf 


AC 


Display a ,f halp :: menu of EXECUTIVE commands and control keys. 


JOB 


AC 


Execute a list of EXECUTIVE commands scored in e file . 


LOCK 


A 


Lcctc (ivrite -protect) a file 3 


MACRO 


AC 


Define a command macro. 




AC 


Iisel&p the cu":eii memory allocation and loaded programs . 


SHllBl^ 




Izbez s ^ nav: c ir ec to ry • 




AC 


Id^esrc s-^tc-:: for REAL data (makes more memory av&iicDi£; . 


?AUS3 


c. r~ 


~'- c - - ' p v = -aoc? :-a -~d wait for RF.titr nt k^y m 






Display or ccacge cic\ ,clcr;£ r.arr : 3 cr subdirectory* 


QUIT 


AC 


l>:it zio I^SII . Ici7_~;ccc z :: cz «pscifisi sys -.;em (Apple) c 


RENAME 


AC 


Change the nans of ? r i c - 


SET 


AC 


Set memory Ioce: Ices co specifier ^ai'zzae cr characters. 


Sill 


AC 


Display tua si^e of a compiled ? RGKAL program © 


TYPE 


AC 


Display c file cf = on the screen, printer, etc. 


1HLOAB 


AC 


Remove c P3.0HAL ercgrac frcrr. memory • 


UNLOCK 


A 


Unlock c 1 1 ' i i:ir.g x ~ rils. 


MS 


AC 


Clear or alter the sice cf the Workspace ( in-memory file) 8 


*Note: 


A= Apple r 


J=Co : up;odo re 


DATE is 


no t a I u i 


-■-t-ir. command on the Commodore 64, but a compiled program 


which is 


autosa ti 


cally rn loaded after it is run. 
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COPY MYFILE.T 



has one argument, "MYFILB • T lf , and 
DUMP 1000 1078 

has two arguments • The kind of argument need ad llf any, varies with the 
individual commands « Frequently an argument nil be a f i.e name to operate on. 

ii e: car ,o v ' ~ a ; tied of e:£ iia.'rs : c "arm o £ :.. 'rave, the 

follcr-irg mention is assn in "his menue!? 

j x ~ .a name sncvrn in a 1 CAP HAL termers indicates the name c t che command 

... - € -crd /-hi^; ; : ' le ' to ~ : mm- t ; ; 1 • ' . I" .mav- 1 5 y -m im ii"her 

epeer cr loner e-se lexers * 

( 2) • A name soonn in Upper and lower case iittcmrm ie a descri~r_ Lor of 

something the user most type in. for example. 

COPY Filename 

means the argument must be a legal rFCMAL filename e 

" f ] anything enclcsad in scene 'e t ^ ~he^£ •• " 1 ] " is optional t the 
ie„m: ri:l e :plain what the default is if the opticnel argument is net apici- 
r e£.. 

( 4 ) . Elliisus i-c^* ere used to show an arntrary nuiroe - z 1 ee : ; eti, 11 .is of 

the preceding item. For exaie.i: 

SET Address Value [ . . . ) 

iiaa;.£ chat the SET command can have an arbitrary number of Value arguments 
9 nee i Ti-d • 

of LB SL4M15 

file names are frequently used as arguments for EXEGUTI7S cemmardfm 
~ila name requirements differ somewhat for various computers, because the cisk 

fcrnaes and underlying operating systems ace different 9 In o.:der to promote 
peroaciliCy bee nee n computers « 1 nOMAL uses a default naming convention thee is 
very similar for all commuters f but may not alien access to ail file names end 
file types chac are legal on a particular computer. FRCrLnt normally operates 
on tnese files automatically ? by cefault e However, provision is mode in 

che EXECUTIVE and Ff.GEAh language zo be able to ^pecace on noij type of file 
which is legal on your computer e Find the file name rules yjhich apply to your 
computer belo&n Hereafter - any re faience to a file name means a ??XHAL file 
name unless otherwise stated. 



which conform to these rules s 




x 1.- , 7r~ rrr.e f£it epliirsllv be f clicked by v. u e ..; i c 1 r r i ~ single 

■/^r 1 ; hi Is ^z:-/ -rsber r Pre f £ Is exterior ''~ a' pr-abe r i*, c •; merh: - T. 
irdicetes the 3 kird !: of file. If fitted* £ isfciilt extension of ,l :C" 5 'rill fcs 
a.sst^ee : ^fiicL i^eie&r&? c P2Glhll cocsfzi rile hsseetst sbbs ^rannrsrl - ircXci^Ls 
character tile extensions may ds used caz are ret recommended e 

[31- hhe file ...err:- t..c <~e £=i -:p:lo:;€,i irl^e ier.be r pr-lir fcll:***eb by € 

:clcr.c lbs choices £r~ 2s or Is- If rc prefix is specif iac ^ is t s 5i::rr i ,. 
fee lb;pe:r&: r. J f c r :.rf Oiir&tic ^ ou rtdciple r^/e SySL&rs 3 

All rornial PRGKA1 fi.es or the CGurxGeore 6-- are stored £S sequent i£l »' SEQ; 

type files, including ereoetEble programs c PS.G ar.d R.EL files are not rrrnaliy 
used • The following are examples of legal P1GMAL file names : 



AB x7 My Data YOUR45.T DOIT.C 

HelloJThera.C T12345.S - Z__ RECOVER. S 

I STUFF 1 % AUXDATA.D 



The tes above which *~"o *? • < t have € fi]? extension wi ? I :?e stored c : f?sk with 
the file SKzezs icr c C 11 • Thus if yor type AB for e file name , t re file AB c C 
will 0£ -re file acced upon (EXCEPTIONS The EDITOR and COMPILER -i 1 1 assume a 
file ex:£u£ icr cf C S fc^ bee source files they operate on) • The f c 1 leaving 

names are ncz legel PROMaL file? for the reasons noted in parentheses; 



7THDATA. S (must s rart with an alphabetic character) 

MY Data (can c have embedded blanks or punctuation) 

THE__LAST__PROGRAM (car/t have more than 14 characters) 

OLD* STUFF. D ( tf . ? can only be used to start the file extension) 



EXECUTIVE comaards normally use PEOKAL file names. However? you may access 

any file name which is legal cr„ the Commodore 54 by enclosing the name in 
quotes » The COPY comma r«d also requires specification of tiie file type for 
ncn-SEQ files > as is cescribed later - 

Appendix M describes P ROM AL support of relative files ? which should not be 
manipulated with EXECUTIVE commands o It is also possible to open files to 
access Commodore direct access files, directories s and the command /error 
channel* These facilities are described later. 
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. 2 - z The name part can optionally be followed by a period and a single 
-.hdriscc:; it^s ^tension. The file £;:"sis ion ~_oSt clp'rabecic or numeric * The 

filE ?rt?'s::r„ indicates the "kind" ~it~ ■ "f orr '~ '*ec - h^f€r,1r ^cst^i^m 
of C ' 5 .2 IE -fill assumed, which indicates s PEvKaL :c-n?ic f- le 'erecnteble 

f regret:/ - r'. 3 ' i *" " p 1 character fit? eyteisicr.e era ~er^i tte' 1 trt rot 
recommenced - The total name including the extension may not exceed 15 
char ac cers 5 

( 3) o The "lie name may have an optional pathname which specifies the rroDOS 

volume tsts tia;or subdirectory name. Volume names are indicated by a leading 
/ character j are up co 15 cnar£:ters long. rrc s':srt with rr alphabetic 
character c T;;, o lume names are assigned vhen the disk is formatted using the 
ProDOS Utiiitjo Subdirec cor ies follow the s&ine naming rules as volumes , and 
can be specified "vher. files are created. If ac prefix is specified sts fart of 
the file ssxs r tkea the current prefix will be usee. The current prefix is set 
by the ? RCMaL 2MSF1X command, and is irl^lnii) c r. a prelim cf che eisk or 
directory from which P ROM AL was bootee c The to cal combined patana^e and 
filename cannot exceed 60 characters » ?er floppy dis^s y \-:e suggest you. avoid 
ciS ing subdirectories . If a path name and file is specified without a leeding / 
character; it -rill be appended to the desert prth. for example if :re present 
prefix is /KYZ-ISK/ , and a name given is PROGS/ GGh Ch then the resulting path 
will be /MYDISK/PROGS/GO.C. 

(4) c In lieu of a volume name, you may use a two character dri^e prefix as 
follows; 

: The / RAM volume t. slot 3 drive 2) 

±% Flop.:" drive i (slot 5) 
2s Floppy drive 2 (slot 6) 
When using the dri/e pre fix 5 PROMAL will read the volume name from the selected 

drive and use it for the volume name part of the fil*» name. It does not change 
the current prefix*- 

The following are examples of legal PROMAL file names on the Apple II : 

AS 1 ,:C My Data YOUR45.T DOITcG 

HeiioTherecC T12345.S sZZ* SYSTEM RECOVER. S 

2 s /WORK! / STUFF / USER. DISK/ MATH/ DATA. D X 
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llw t» VAC 



Is ":3j : ;i'E _ or r^end tc- co r ' 5 -^e PRODOS system 



i J ^ Z c ! • 



^cic lists che casccx^ary file extensions used for various kinc. 

i^a.,a : ons r> y be devised by the user for special need: 



PEQMJiL f iL£ EXTENSIONS 



c " *_e { compiled) PROMAL program® This is 



n E ?£0OL 5MP5£X' file z :r c£para;e compilat ic n- aasjrlte^ in 

Gnspter S cf the LANGUAGE ilAlFJi^l) o 
o J A r : Jc b file, visaaiiy prer&rsc- -?i tn cbe EDITOR, usee to drive the 

EXECUTIVE fren a scripc of commands. 

• L§ A 'c rGg r -suv: listing 

• R A Commodore 64 relative file (sea Appendix !€ ) 

• S A PROMAL source program, normally prepared by the EDITOR. 

• T A text f ile c other than a PROMAL source program. 
•X A cross-reference map (output from XREF utility) . 



numeric mmmms 

Some EXECUTIVE commands accept numbers for arguments The built-in 
EXECUTIVE commands all require numeric arguments to be specified in hexadeci- 
mal o User-defined programs may specify decimal or hexadecimal at the discre- 
tion of the programmer. It is not necessary to understand hexadecimal numbers 
for casual use of the EXECUTIVE, The Commodore and Apple Reference Manuals 
describe hexadecimal notation. Hex numbers say be specified with any number of 
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You do not use the $ prefix for EXECUTIVE commands, because the EXECUTIVE 
implicitly expects hex values. 




SET 5000 "Now we r earn PROMAL 1 1 

will = Cu*. ^tir^ quoted charade 2, 1 .g as one argument , >.nd nil: not 
co river t I: to uoper case (this commas a installs :ae siring specified into 

memo 17 sterling at local ion 5000 hex). 

DEVICES 

The PROMAL 31EC r Jll "E ' s ? *-eil a? rROMAL programs) can perform input arid 
outpuc cc csrcair z~~-\z~z £z veil s: i i „ e 3 • PROMAL devices are named with a 
single charac ter as ;ho^i in 7s 1.1a I- below. 

TABLE 4 



DEVICE HAMES FOR PROMAL 



Name Meaning 

S The Screen, For output cnly & 

K The :£ey beard , For input only c 

P The Triicere Fcr octpnc only , 

N The lull device (discards sll -rtpr *: / * Fcr output only, 

W The Workspace { in-inemcry file', c Fcr input or output, 

L The Library {ir-ae^ory file; e Hormai7».y for input . 

T The Telephone (modem)© Fcr input /output .„ 



Most EXECUTIVE commands can accepc one of these device names anywhere a 
file can be specified. For example; 

TYPE L 

will type the contents of zhe library or the display c 

The W device is a simulated file in memory, also called the Workspace© 

Although the Workspace is small compared to a disk, it is much faster* The 
Workspace is often used as a place to save a source program you are working on 
temporarily • The size of the Workspace can be varied on the Commodore 64 by 
the WS command. Naturally, if you turn off the computer or leave PROMAL, the 
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of the works pace j "< . ~, 

command « 




>"c a : PZ£C ! /TI rcr c:T./,:-r''s normally output to the screen. However, output may 
01 -~slr r-srtsd *: a 7?-! c t cevice by using the redir-r -_i' a op3r-.:*r ">" after 
t - 1 1 £ c c rg"rc~ " T" r € >:amp le J 

TYPE MYLETTER. " >F 

¥ij.: type the file »dYLETTER.T on the printer instead cf the screen, Sim - . " 
the ccmmand 

FILES ^¥ 

v - I :cux\ che ca~ ~ s cf 1 - : . % - : ~h~ - is ^, t - '"he Workspace, You may 
*lsc redirect o^cpu: ;o £ iils : lor e:>:a~p la ;; 

DUMP 4000 4100 ^EZPG-IF~1 

will oat put the memory contents cc the eexc file XEhD JMP . T instead of *„c the 
screen as it normally **jcu] d c leu car only redirect output to one device at a 

time. 

Many PROMAL programs slsc -lie--" thal^ ?-jtput :c be redirected in the same 

manner. Suppose thst voir had an application orcgrsx * 7 hich produced verbose 
output on the screen eace c ime it ran,- ar?d chat yea wanted to run it without 
seeing any output* Yc r can cc thfs by redirecting :j : :;ut to the N device • 

Some PROKAL programs else- a 1 1 c r incur rediracc Ion© In this case, the 
program normal ly accepts i npu_ iron the key a oar c : hut can alternatively accept 
input from a file cr device e Ic redirect input f the input redirection symbol 
(<) should be used after tee las; argu?..er.c s For example ? suppose a PROMAL 

program called XIWSnlC&Y nerval ly accepts input f rem the keyboard and generates 
a file specified as the first argument. You might tell the program to take its 
input from another file called APRILIHPuT© T instead like thiss 

INVENTORY APRIL, D < APRILINPUT. T 

The programming techniques for interfacing to the EXECUTIVE are described 
in the PROMAL LANGUAGE MANUAL, and make it quite simple to support this Rind of 
command • 

PROMAL EXECUTIVE COMMAND SUMMARY 

On the following pages are descriptions of the individual EXECUTIVE 
commands* Commands are presented with a syntax definitions a description of 

the commandos function and examples of use. Unless otherwise noted, the 
commands are available on both Apple and Commodore 84. 
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bujwkks 



A h _ Ac . : ... ll l\ o** <. , r . ^ - rr t - - - -.r -~ • n " r :. ^ * - - l -£jL~r c 




^rg'rrsr:r ? i - 7 1- re number ? *n* ~ r e jer. : '.• " y -deigned-, ryrrrg ?. T^:csr 

-f:%: 37751?.? v"lll sec the -:^n:£: .. 1 brffeii sre^:liric "rttirg the number of 

brffsrs vill causa ell programs is re reloaded, aac will effect the memory 

map, PROKAL allocates tre brffers :s:r" the av = r leb le rrcgrEm space. 



You also use the argumenc HlitEr or in combination with a number). 

This will cause PROMAL to urlccd all programs in memory and reserve space for 
the hi-resolution graphics "page 1 fron 52000 to $3FFF. This wilt oe necessary 
be :cr ~ running rrr 7 or eg ram which uses Apple Hi -Pre? Graphics* You can dealloc- 
6 :r Ira hi -res t : v \ typing BUFFERS with a number but without the HIRES 
argi'j.e.itt 

Example 1 ; 

BUFFERS 

will oispls.v the current -number of 102*«i buffers reserved , for examples 
NUMBER OF BUFFERS = 3 
Example 2 s 
BUFFERS 1 HIRES 

allocates one 102^ Ilia r^Zlar pl~3 an 8K byte hi-res screen at $2000 o This 
will of course reduce the sisa rf ^ 1E0MAL program which can be loaded. 

Notes : 

1. You can include a BUFFERS command in a JOB file without harm, even 
though the buffers for the file may move , so long as there is a buffer avail- 
able for the j cd file yhen the command is completed c 

2. Reducing the number of disk buffers below three may adversely offset the 
operation of the PROMAL COMPILER, since it may need up to three files rrt once* 

3 . There is not enough free memory to COMPILE a program after a BUFFERS 
HIRES command . There fore when developing a graphics application, remember to 

switch back to normal mode with a BUFFERS 3 command before compiling. 
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™ Change text and background col: _ - - 



COLOR 



AVA1JLAJSLJ& 1 














*■' ^ ^ 


r- f Kir 

£ j Di\, 


; ■ ---•-:•„ 










^ - -* 


£1 ~ 


r -n % - -I 

: ... . t>1C '. - , 






colo 


5»r*"' ;* 'i 




C - - 1 








; ! ;r: 






T*. *_ ~T C 




r o «s - -f* c - 








lugs 














BLACK 


4 


PURPLE 


8 


ORANGE 




C~-£.Y2 


1 WHITE 


5 


GREEN 


o 


BROWN 




lyc'illn 


2 RED 


6 


BLUE 


A 


LTRED 




LTSLbE 


3 CYAN 


7 


YELLOW 


B 


GRAY1 




-2 EA 1 i 



The second argument is c^ticnclc If speciriec it pslsc'c the rsckgrr ur:c 
color. If riot specified, the background colci is unc.~«sng£:U ilazcrs 1 1 j P if >ju 
select the same foreground and background color 7 she - T ii 1. irr*isibl£ 

(but the computer r " 1. c i:' "see 11 what you If ;Cw 2zszi* c / s r.urrisar 

greater thar, $I\ t;:.o EkZGUTIVE will force i; ic.cz, z\e raeg£ r " ? zc 5? by 
discarding -.11 cue the low order 4 bits, lames must be spelled exactly as 
shown above in order to be recognized (for example, GEAY2 is okay but GRAY 2 is 
not, nor is' GREY2) 

Example 1: 

COLOR PURPLE 

selects purple characters iron t - is ?3 ir?l cn. 

Example 2s 
COLOR A 

3 = l£ ? ".c i igi •: red characters on a black background, 



COPY — Copj file cr demise ~ COPY 



COPY Filename 
or 

COPY Source Bbsz 
or 

COPY Filename Prefix 

The COPY command is used to copy the contents of a file (or device) to 
another file or device* 
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: 1 ilr 



.11*2 UCO t, HiaLiUti IUI 1.1 

if : iri/ib-ts ~:vi i: 



copy. 



The c -: p - : " i? v^ce 



Sot:. : * f ::. - _.v " ~ ..; ; 
Sour s r c the ce 



- names or ? 
Ihe destine" 



s names, 
r - -Lame 



in , 



ii:vfrr^v: 



:srx : the iirsr ergrrsvc pust be ~: ilIe - - me - not a device 



n e ra i £n 2 t : s c a : c v : 

will be copied to the 



■ "rvv: :v : rv* 



: ec ignator . The file 



Fo r ail file « _s ae c 



specified pre:ix " • 1 c p. cha same name * 

:i ie c-,. e..s ions wi.,1 le app„i^d except for 



Exam;: iec for ipple ? 

If COfTrlgCf jg . ^ 

COPY 14 7F~LE 

COPY rlYF^LZ 

COPY ; :r!IFlLi 

COPY MYF ILE • T YOUR.T 

COPY PROG.S W 

COPY 1 ': 7 ROG • S 2 s 

COPY MINE • S YOURS 

COPY L S 

COPY COMPILE 0: 

COPY "PROBOS 11 2 s 

COPY n PRODOS 1 ' "2 2" 

COPY /MY* LET/ JOE. T 
COPY 2 1 PROG.S P 



i~ a* -- " r~ a 



eir-g^e a rive 

2 d r 1 ?e s « c at re u t 
prefiv 2t drive I 
err rent prefix is 
/ RAM/ (RAMaisk) 
anything 

anything 

anything 

anything 

anything 

anything 

anything 

anything 



current prefix is 

/ TEMP/ 

anything 



viil copy MYF ILE. C to another disk, 

prcu.pt in g fcr disk changes, 
copies MYPXLE.G from drive 1 to 2. 

ccple? .FFiLE.C from drive 1 to 
/ RAM/ . 

copies MYF ILE • T to YOUR.T on the 
current pre fix . 

j^pi-s PEGGaS from the current 
prefix zz- the Workspace ~ 
copy file PROG.S from drive 1 to 
drive 2 3 

copy fiia hllTZ.S cc ri.e 

on the current prefix- 

copy the L de -ice (library) to I 'is 

screen o 

cop> COiirlLE. C from the current 
pre f iv cc che /RAM/ disk 
copy file PRODOS from the current 
prefix to drive 2 and change its 
v^rrB tc PROPOS.C. 

copy file PRODOS from the current 
pre fir, tc drive 2 with the same 
name . 

copy JOE.T from prefix /MY. LET/ to 

/TEMP/ with the same name . 
copy file PROG.S on drive 2 to 
the printer. 
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where Pattern is the desired filename pattern with wildcards, and ir <~c : - . \z --"-e 
^3 = U",: t ion prefix. 



Ex air 

EXTCOPY *.C 2 

:c:i3" - . ... ilia: end"-" o o r. ' , t 1 '* 



he / RAM disk, 



for ..r^>^sTi V:- 



._f o.o_y one argument 15 go 'e.:. . t,.^c ^ 00. a - 1 . an.- c noc & ae^ice name. 
v.;& • r.-.ve net ha^e £ c : i?e aes ign&cor spec ^oof . Yea -7:. i be prompted to 
. . cilc^.iso f:: sooglo drove copy • 



— 



:;ai , th c g r -- rcs - r J 



is o-ace ::ci 



so ~r: 



rive 



-gn£ 



if lexsc or oo~ 
loo dsccir.stj 
r s used • 



2" noooss c 
o file name 



tho third foroi f the fi s t ^rgunent must be a file lame ; noc a devils 
name, arid the second arguneot ^lvs t be a drive designator.. The file nil 1 oe 

copied to the specified drive with the same name. 

ifT ' 1 file name 43 de~0w't f i 1 z ~ itensions will be 000 1 4 ed and € file type 
of SEC "ill Is used, except fcr arguments in quotes. for isqes in quotes, 110 
de :s ol t filo entens ion irl 1 1 ce applied ? and you may specify a file oype 
3-7: i^itly by appending < o~roo.- £.i~ letter 5 fcr SEQ ? ? f ::. or U for 

USR) to the name inside the quotes (for e v '^p la r "Basic Prog , P" • When enclosed 
in quotes, names are case-senc it ivo . 

Examples ic~ I'cmmodore : 

If comma no isr - € Thee. . 

COPY COMPILE 

COPY MY FILE YOURFILE 

COPY SOURCE. S 

COPY .SOURCE* S W 
COPY W S 
COPY MYFILE 1 ? 
COPY isTESTcS ? OLD TEST 

COPY i J TEST- S C2OLDTEST.S 

COPY TEST • L P 
COPY "PR0MAL,P' ? 



i#iil ccpo CClIPILEcC tr> soother c<-,$i-\ : prompting 
for ais*c ^catges "single dri^ e copy}. 
«7l1! copy LYFibEoC to YOUlFILioC on foe 
same diske 

cecy S0L ,p XSnS to soother disk, prompting 
fcr eisk changes (single drive copy) 
Copy file SOURCES to che Workspace, 
Copy the workspace to the screen c 
Copy file MYFILE. C frox drive 00 drive 1, 
Copy file TESTc S from drive 1 to cr " v = r- ^ith 
a name change to OLDTESToG 

Copy file TESTc S from drive 1 to drive with 
a name change to QLDTEST.S 
Copy file TEST* L to the printer c 

Copy file PROMAL of type PEG to another 
disk, prompting for disk changes (i drive) 
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prompted : 



-.PI'EIT ?.iI-Lr.:z e ~fi CANCEL (A/R/C)? 

?: £ 3 5 the a. nay :? ainsnd onto the end r f the e^ir-inr f- Is* 1 to replace the 
srJs^ng fila 5 :i I to cancel the command • 

fetes : 

io idc ¥1 1 . hoc oe a^ '■ e ^c c p^and the Workspace; copying zz Ic cie.frds any 
previ : as c*n;enls £ 

do 3c not az carupt zz anac^ce a, utPY comma n^ :r:^ a J zz r i'^a cr & disk in a 
single cr i-e ?} ? $f~er II chs cc-r" * i " reqnira rf.sk ?f c :os , bec^-isa ? ROMAL *vill 
attempt co rest the .J IE ri„r ~'hile yrizr f e 3 t irr " i cn zzzz s z : - :ha drive . You 
may execute snot ? ic: rile by first, --..no ~i-:;g zlza job file cc :.he Workspace and 
then using a JOB : *~ comr a \ 

3 . See AjppsadiK IC for. leasee, ere iarl a rive installation instructions . 

4. Do hoc ectstap: cc copy Cc-modore 64 re latins files e 

5. On the Ap p I a . at tairp t rng Lc replace £ locked file tfill give a WRITE 
PROTECTED error message * 

6. Attempting to append a locked file or fila cr t a -rrice projected disk 
•-ill c reduce a JIS^I SR?0? aes-egec 

7 - Copying a fila to the <v ne^lca -M.zch is larger than the workspace n 7 iii 
result in a DISK/ DEVICE FULL error with the rest cf the file not copied, 

S . On the Apple ? copying a J '° 1 Iron era drl~~e to another --hen both drives 
have the sars volume name rill gi^a an 111 EGAL FILE/ DEVICE EAME error • 

9 u The ^ jy vv.s:SdL:d uses the f r ~e memory apcC^ a zzz .1 r ...If a..: «■ 

f'carafcre yen can increase che af fie fancy of copy opera lions (especially for 
single drive capias} c y UNLOAIing memory before copying c 



CS — Clear screen and hone cursor — CS 



CS 

The GS command clears the screen and moves the cursor cc the home position. 
It does not have any arguments e 

Example t 

CS 
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DATE 



~ Display ami set date — 



The DATE command prompts for the current date. It is the same command that 

is exec ~a ~ r 1 ~ ^ " ~len -"""O ^L cr Ti"T ^15L- ~v II \ e ;'-ei.d; 

entered :rz. o~ >.z v _ i _ ricilf ' tna O^t rue _.;„o.. t ^ /_ „ tnu 

des irec ~£"~ fuu rv = u::u :hn cane r:-:!" ~ ~u~ '. u; -vl ~r 1"1 TT 1 ;"" " l * ^. 

pre sent i : - / n i 1 7 C—AL r , t _ 1 1 : _ ' ' :. ' -s - - - " a ~ z c " a i; - i ; c - ~ p z - " - ' 

prog r air.- r ^-r -u- t -n - : ' " ~f i? ~* ^ a : i : r r, : s i: ; i " z 1"\; sd •: ; " 1.. r ? 

command uvev ;-r ~ e. ar..? -re 1:.. -cv r y _ or y : ur:a 1115 rcrrr-rc ii ":<--6~ y - ~ a 
fir 1; - 

Ex any: Is 5 

DATE 

Today is 9/30/86 

Please enter t c d a y ' c ^ a :: e - 

Note . 

1- In a -ycLa 1!'- the date will la updated autcua: : c^lly ~r systems with 
a Thimderc lock or equivalent card when the DATE command is azseuted, without 
any prompt or user action. 

2 . On the Commodore 64, DATE is not a Guile -in command , but a separate 
program, which is autcnat icnl 1> unloaded after it executes. Therefore you vill 
need to have the f i la DATF« C cn your boot disk co have the DATE command run, 

3- 7- no 3C1TSG"^L\ 1 is rveserr cr. :ze boo: disk, the PROMAL EXECUTIVE 
will execute ZAIE autc.Ta tics lly dui log bcotup. If a BOOTSCRIPTo J file is 
present f DATE "ill net be areola tics lly executed, so you should have a DATE 
command in yc or B CITS 'fill?! . J file uu 1 s s you don' t want to set the date ;'sae 
JOB for mere in format :oi ; „ 



BELST1 ™ 3si<s££ file irom «£i^aetcry — ■ DELETE 



©ELITE Filename | e c j 

The DELETE cemmand removes one or more specified flies from the disk 
directory* The file name(s) to be deleted should be specified as the argu- 
ment ( s) o Wildcards are not permitted in the Filename c lou may not delete a 
device, only a file nane c However r typing DELETE y will clear the workspace. 
Attempting to DELETE a file or a wr i te-pro tec ted disk (or a locked file on an 
Apple 11} will prod j je ar. e . ror message c 

CA!JTI0^c There is nc prompt for verification before the file is deleted, nor is 
there any way to n un-Ge_ete r a f i 1 e ? so use DELETE with caution* You should 
maintain lackups of all important files (for any system, not just PROMAL} o 

Example 1 

DELETE MY PROG 



Copyright (€) If Si SMA Inc. Kev, C 



I, DELETE z-zl- rscc^: e c dl- i^crr ddsx director" , If :he ctl-^r. fid: 

i? r program -d i r d ii ^Irc It Memory, ic is coz r.?moved from memory and ce~;, 
?-dll 3e exe a , lh~ r Jd- O^D command removes the memory-resident progr^n - 

2- On the A.opl£ Ii : nay ilia's subdirect :rc Lss , provided they are SFipty, 

Remember to ercl3?e :de fiara in quotes. 



DISKCMD — - Access disk command /error chacrrid — DISKCMD 



e?ft±^£rr§^ dilldE rd-. ItsJc CdddLd3LC ; fdl 5^ 
dlSxGMIl I Coram } 

The DISKCMD can be used to send a conn and to the Commodore disk command 
channel £.-d : . : 1 = ; 1-..; jr. a status c£esags drcm the disk error channel . For 
normal operatic^,, tdd; ?cnmand is nevr; rcaled, since PROMAL and the EXECUTIVE 
ncrxsliy handle '11 :coi£id/error processing transparently ~ Yc u shield use 
f'^ds command onl;- lor special c ire urns t^rc~~ requiring spec r~ I a'^sd "cmmands . 
~ p „ r argument" df pp - ~- Hie current sZz*:ns vriil be d l:-p?.^ysd ^ "z" 

ex amp* la § 

j OK cud G L? 

If the argument is specified ? it should be a Coramccers aisk command enclosed in 
quotes , 

Example i 

The f c 1 lowing command will irrrsdiiPt'sdj dcr-.£- cds disk current ly in the 

drive f erasing everything currently on the disks 

DISKCMD "N0:WORKDISKl,K6" 

CAUTION: Be very sure you really want to format the disk be fere typirg this 
command, there is no chance to change your mind I 
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DTHO = l-dr jr dis^. r double spaed disk — DYNO 



DYNO [Onof f ] 

-R^IIAL for "he Commodore 64 has DYNODISK, a % vii : :==ir software package which 
sf :i$c J -i-eJv~ -'>*v3les th-e ~emd speed from Ccv-:d^ra cr j c " ^l?k dri-es. 

Leediess tc say, this is a tremendous asset ? since the Commode re disk is 

1; slc/7. DYNODISK works vi cLL f ilo: c act jrst programs Lhe DYNO 
command vi;r ac arguments specified viil cvioplay eke :j:rsi: DYNODISK stacks, 
either iH or OFF. The optional command Czizz 1 :: vast ca eikaai the wora OK or 

OFF, and turns the DYNODISK feature on or of 2L 

Examples s 
DYNO 

wi 1 display tea current states ? al~h^r ON or OFF. 
DYNO OFF 

disables DYNODISK for further operations :v:il earned back on. With DYNO OFF, 
the 1541 will operate at normal speed. 

yores ! 

z. ~ DYNODISK cannot be used with MSD arises or other drives wbv ^ a a re cor 

:CC% ccmpa t ible with the 1541 • You can permanently disable dyaoaisk by setting 
-he o : ce a. S0LE2 non-zero. Do not enable DYNODISK with Skyles FLASH or with 
ccher commercial disk speed up cartridges or software, Most other commercial 
disk speedup products do not work with P ROMAL at all because they use some of 
the same memory needed by P ROMAL • 

2o Like any 1541 speedup package, DYNODISK does ha^e its drawbacks e if jou 
hava s priater cr other device on the serial bms s it zr^sZ fee turnmd ®££ while 

DY&CSXSK is ON© Failure to observe this rule may hang op the system 9 requiring 
a re-boo t of ? ROMAL « If yea have a printer vita an interface cartridge f it 
must also be off while DYNODISK is c: : Only * single drive is supported. 
Having DYNODISK on reduces trie ::. .:mz e r cf baffers vhich are available inside the 
1541 drive „ Therefore yoa may be able to have fevjer open files vrhile DYNODISK 
is enabled o DYNODISK disables interrupts temporarily *hiie it is reading from 
disk. Therefore you v.ill act be able to use CTRL-STOP to abort a program while 
it is reading the disk srich DYNODISK on. 
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• •; / '• • • .. •• . . . . " *; - ... - . ' ^ ^ * : ' : , - J \ .:. ■ • • ; .... . % -i- - ^ 

** . r I r : i : i- \ ; ; _ ~ - 1 ; : \ .; : ; •: _ '-. - I ? "'.'* • - ' ' 3 ~ ' . v-. 11" - ' • ~ : . 

~ _ " 7 - 1 >,2 I . .:' 1 U T ? ^ 1 " - ~ 'I \ V, 1 " ' a. ^ i" ^ 

PUfP — Bisplrrr ussier j in Hex and ASCII — DUMP 

DUMP Ad,- -3 ?^ [ ToAdr ? s c > ; 

The DUMP command is usee, .,c aisol&j c> ragicr cf memory on the screen in 
hexadecimal 1 z< ' ; ~"C11 :i-rr':,^ : - Trr fircr '"'^'inen^. is the desired 
starting arcra^E. 11 a secor.c , i^jrirsl £ig:;3:i; is an ending address • if no 
second adcrsss i = apsrifird, oignt 1 yccs ::::: be displayed • 

Ex amp las ? 

DUMP 10 AO 

w: 11 ^l^plsy -igh" cf:zs ? " memory beginning at S10AQ. The display will appear 
siiTaila- ~o ..Lis! 

10 AO 50 0C 4C D6 29 4B 00 52 lolcJIhZ 

Tee fc^rtirg address is shoe 1 cl a 1-1 -<\: q " 1 :mn • Trie next eiglt 1 -digit 
groups show the hex values c: 11-. 0A0 rr ro .:p r 51 'J --To 3 grrr&t c " ; c ''ows 
eight characters with the A 1 C 1 7 rhar£cl;er cprirsla _1 ?1 r$'h "1 the l;:as : 
Bytes which don't have a prirtille *„5CII rhstFrirr ' rrr Iralr^ Hanks; srs 
displayed as 11 instead® 

DUMP 4000 41 DC >? 

will dump the corlHr^e of 54000 through $4100 cc "he prir:~r. 

Note; When an e il address is specified c a cerpleia ...una --ill always be 
displayed even if it "evershec t s" the final address „ Th^re f ere che above 

example "fill actually display $4000 through S4i" : sin^e S^iOO rill fall in the 
first pe&iticH of :. „s Issc ii.rs cf the output. 
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EDIT [Filename] 



Exam; 1c ? 

EDIT MYPROG.S 

edits ere file MYPROG.S 

Note icr Jo&s&iore §4 systems! Normally che EDITOR is always resident in 
memory and will start immediately when EDIT is typed* However , it is p :sr : 1 e 
to unload the EDITOR frrr. s excry b) u&lrg the ,f x ! :-p ::xx. rx-xiog the 

COMPILE":! :c free up ^ecr, f ? r -:r_e syxbci rxc 1 e . ? e c xx~ Ix-xxLER section 

c f xanuel; * Ix cr is :£c6 :re IlliCr xi 1 .» net :x:: i :el ly : 9 re 1 reded from 

disk when needed, The la Iccx -'ill elx^ be ^elceded free d ° sk If _he EDITOR 
program has been corruptee (icr erxxpie . by ax errant user xregrax poking 
around in memory) . Yc -c xey EDIT laiger lit^s by UNLOAD! f»g r^cgraxs o r clearing 
or reducing the Workspace be; 1c re fteitlug che Z,c 1 tor * 

FILES — Display diskette directory — FILES 

FILES 
or 

FILES Pattern* COMMODORE bx bxLY FOE THIS FORM 

or 

FILES Subdirectory APPLE II ONLY FOE THI3 Ix3f 

The FILES command is used to dispiey che nexe s rf files on disk„ 

UILES for the Ipgls II? 

If no argu-rer t ic si '-arts ell files on the current prefix xill te displayed, 

in four columns*. If an argument is given, it should be the desired pre fix No 
wildcards are supported e 

Erxxc las : 

II^ES Disc leys ell filenames In current cretin 

J1LSS 2s Displays ell file names ce drive 2 

111SS /USER. DISK/TEMP/ Displays ell files in specified direetciy 

?1LES Os >F Prints the names of s 11 files on the / RAM disk* 
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I--; h, u. p lo5 - c r Ap p 1 e i 



EXTD1R * 

EXTDIR 2s 

EXTDIR /TEMP/T*.C 



Displays ai. 

li-scUys a! 
tension ri 



,1/ 



_ ^ — ^ u . 



You 



need fila 3XTDIR.C 



co;;.r?.£:c 



Uoramc 



Th~ files will be listed on the sr^e-* it " h e 



f c a a rcr B~S T J r 



zc :£cc::'' sr in th~ tc r r..r r r : r 
LI i:^£ file? c«i thr will 



inclu i i j.c rha £1 Lr cii^s. Wild cardc rr;r*" ha ^ .. r :, 13 :i: 

f Lifts 3 ilia wildcard chr cszz i r - operere 
1541 DisK Manual® If no r^treir is sfa.lfiac 
be displayec- e The size cf ssc'r IrLe i-? nea^r-rc ir v.o^;r drrr Blocks : r /r_ a: 
256 b/tas eact : '"Tie num-: c * spieled ii rr dscLrs^j ret rer . Di spl^; v i rr !r; - 
doss not affect programs in memory ♦ The wi Id cards allowed are - and ?. The *. 
character matches any string, and the ? character matches any sinrls character 



Ex amp la e for Conmodore 64 : 



FILES 
FILES PRO- 
FILES is 
FILE' 



Displays £ll f rt v; rr d . i^r j 

Displays all iile* c U_ ' rig ->ith "PR" 

Displays 6 1 _ frlr^ ^r ~ ~r t c 1 
Prints thr rrzir? cf i '_ 1 c l1^ 



Mote : 

1. You might suppose it would be pcs-srcra z: d i r ~ ~ ,v >~ - ~ - -~ r-^e . vith 
the extension ,f ,f by -sing the ff ?lLZS *,S" ccrrr,rrr tjr tcr t jrrc s I / , : r ^ 
Commodore ROMs in the cisu ariyc ce act interpret Ui^ - lr r ? • d 1? -af , 

'".'cc c - ~, rt ~ d i 3 no 
nly useful for 



Instead, the rrtcsrr is interpreted as cacrhirg di 

matter what the r-aees ar^ Therefore the - "rider rd io 



matching names rich a :c^rr 
wildcard caarr: ' te jrsd to • spfs^r.;. 2 coo;: 



r*s :rr **hich differ ~rL 



su:- rr 



2. Redirecting FILES to the printer prints one file name per line* 
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FILL ----- uu_r>^ €._^ : t1 :1- _^v- : :-u: - — FILL 



FILL from To Data 

first argument , from, is the starting address. The -second argument 

l;rj71Lll~l: If -"cu r£,r„l . : a^:: ar iment with the FIIL command , specify an unused 

^re£ rf rs; : ,?*r:r fs ?EEE SPACE" by the Mar command) . Indiscriminate 

us^ c " -".r^ FI_1 ro^L^-ia ecu Id overwrite important programs (such as PROMAL 
i ': 3 3 ^ \ ■; u uemory . 

Ex amp is s ? 

fill- *800 4923 
' : +800 through $4923 with $00. 

TILL 4210 4310 # # 
fills $4210 through $4310 with ASCII blanks ( $20) . 

FEE! — Display or change fuaetioa keys — FEMY 

FEE? [Kay number String] 

The F>2Y command is used '■*•- ^ispl^y -~~ I'^gs the meaning of the function 
rays : /i -:hrougr Fe. If no arguments ara gi j €u t t"is current function key 

ds finit ic-r s fcr ^1.1 function keys will ce 1 L& c 1* zd . If the : pcic ^a! argtrrsite 
ere spec, f iaa ? than the first argument is tea Fcsersd f unc t icr key - c;nc a . tc 
change c i through 8 * The second argume nc is ;ra desired char a: ts =. string ha 

substituted when the function key is pressed - ina String may be up to 31 
characters c r,g . If it contains blanks ? char, it should be encloscG in quotas - 
Only normal ; printable characters can be inclu^ec in the String. Cc rtcei 
characters ( such as RETURN) cannot be embedded in the String. 

Examples % 

FKEY 

•-•ill display the current function key de f ini t ions . A typical display would be; 
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f; - fs = copy 

This is ;/£ acrr.-. - , Sanction key -i^lLi-A.A _ at power -up . 

FKEY 2 MY PROG RAM 

changes function key Iz to generate "MYPROGRAM" when it is pressed • 

FKEY 5 "COMPILE MYPROGRAM 0=NEWVERSION" 

changes ?5 to be "COMPILE MYPROGRAM 0=NEWVERSION" . 

if you wish to ha i e C€r:e:i fci;'::on keys a .c v -5 c I rdl 1/ defined when you 
"boot up" PROMAL, you may do so simply inducing r±a appropriate FKEY 
commands in the B00TSCRIA1 , . .Ale c>, „ our workiiu rAs^c^t^ 



SET — Load program ircm diskette ~ GET 



GET frog name 

The GET command is used to lead a P ROMAL or machine language program into 
memory without executing it-_ The argument Progrssi; is the desired tile 
name to be loaded. .Arr;,.alt; it is £ legal PROMAL file - ame , written ^itArrnA 
quotes r, Only compiled P RCrlAL rrograris {cr relocatable machine langu-ga 
programs in the ? R0MA1 f o -qa t as dese riled in Appendix I) ran ha loaded using 
this form. An a ^ temp : ~o GIT s lite c* another type nil 1 result in an error 
message. Af to * -A - e p ragman, is loaded; it ~fiiL appear en Ana ilAP display. and 
can be executed immediately oy typing :;s name . 

Alternatively, the Program can be the name of any non-relocatable Machine 
Language program, enclosed in quotes ( ff ) . In this case.- the named machine 
language program vjiil ds loaded into memory at the address from which it was 
saved . No checking is done for overlapping of other programs , nor is space 

allocated for che program in the MAP. See Chapter 6 f function MLGET in the 
LIBRARY MANUAL, and Appendix 1 for more details. 

Examples : 

GET SORT 

loads the PROMAL program SORT* C into memory (because c C is cue default 
extension). The actual load location will be determined by the L0ADer f and 
can be displayed using the MAP command • 
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z^z^e, 



Notes % 

lc 1 . : . ' z:j- \ r.rsrc: s -; 1: rr^li'.nc 1_ n z ^z z, ' ' : ect 

tO t • ■ r ••• ' Z Z f * - : - ■ "— l~! '' ' "/ ~: - f " , rV* c- ". "* 1. '; -j* *~£ 1 1 "^l^CtT- 5 - J* ~ 2, ^- P ':" *- 2_ 

prog - ' - r _ _ , '. . . r * . " .. : , 

LOAEc „ i _1 urlo.d . ... 2 running ~ : itr jL-, , - ., ^ ~ 

ed prcgr r.i« L'sia is rgb Vh«=r. cha c.:.j^i _ _~n: ed ? ~hc 

LOAEer nlso computes and 2 a-ec z ^'checks urr : cf rhe program image in t^c:;: 
When you subsequently e^e^r^ the program, the LOADer will re-ccmrure che 
ciec ;? ?i-2 and compare it :o cce saved value . If the two values differ ? it 
indicates that the progrrir !n has been corrupted (by another prog ram) , 

aa: £G clc ^OADer -111 ra-loet s/na urogram fron dis^ re fore executing 

2e On era Apsie 11. most machine language program." 3 load irrir-^lly nr S2G00 
and then "relocate 511 themselves to their final location la order to load such 

a program with the GET command, you re-h to do l BUFjII? HlrES ;:or^a:rd f 1 r 3 ~ to 
free the space from $2000 to $3F?Fd You also need to insure zzez the program 
will not have any other memory "collisions' 1 with PROMAL, including its 

lf raicrated" des tins t ion * sero page usage, sic ~ 

3. On the Apple II, if you GET a PRIMAL program, and no error is Issued, 
but when you use the MAP command it does not appear, it means that your program 
was successfully loaded ? but was immediately unloaded when the EXECUTIVE was 
swapped back in . You will need to UNLOAD e If the symptom persists, then the 
program is t c : large cc fit 1 . r.amor;/ at .:he same time as the EXECUTIVE ; you 
can execute it by typing its nanSo bat you can't GET it from the EXECUTIVE • 
The COMPILE program exhibits this characteristic 

60 — - Execute Machine Language program — GO 



GO Address 

The GO command is used to execute a machine language program a Ire 3 ay in 
memory (not a PROMAL program} The argument specifies the starting address for 
execut ion in hex . The GO command cannot be used to execute a PROMAL program o 

Example ? 

GO FF81 

will execute the machine language program at address $FP8i. On the Commodore 
64 s this address is the Commodore 64 Kernai routine "CINT" which r e - i n i c i a 1 i r e s 
the screen and video chip 

Notes : 
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p 

6B-" 

AT 



BRK HIT 

S 

F6 



This display gives the collate c f ':is 6502 r9,gis"~*9" ?~ : re time *- re 
breakpoint s.ig rhe address rf die Fill— 1 las true t Irr, " : L:;h lad the n.^xie 
language rci." t ine • If a GO command was user c-irsr the program r it will ?how 
the starting address instead. 



HELP 



Display help screen 



HELP 



HELP 

The HELP command displays £ finals screen. : 1 rr.fc rotation showing some of 
the control keys used for editing and a list z, £ the most commonly-needed 
EXECUTIVE commands e 

Example § 

HELP 

on the Commodore 64 will display a screen similar to J 



PROMAL HELP 



CTRL- 



;trl- 



Delets Char- 
[ GRSR to s:£r: 
Y GRSR co End 



A Upper Alpha On/Of f 
B Recall Frier Line 
K Clear re End Line 

P artial Coinman Q Summary 
COLOR [Colorname [Background]] 
COMPILE [File » L>Lis c , 1 [ C-Cb isc t ] [ B] ] 
COPY File [Desto] 



DELETE File 



Func t ion Keys 



DUMP From [To] 


Fl 




EDIT 


EDIT [File] 


F2 




DUMP 


FILES [Pattern*] 


F3 




COMPILE 


FILL From To Vaiae. 


F4 


22 


GET 


FKEY [lumber String] 


F5 




FILES 


GET Command file 


F6 




MAP 


JOB File e J 


F7 




HELP 


MAP 


F8 


22 


COPY 



RENAME File Newname 
SET Addr« Val [ VaU • . I 
Type File 
Unload [ Command ] 
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— Execute e§«ails in job file ~ . JOB 



7h c 111 command fll: a "he 1 JH""1 re 5 11?; rl crrtrrrr a 

rile or dish instead of the hevbe^is This is s ens t Iras s cslied a ' £ b£tch" : 
2 € p a : 1 1 z ' 7 >- Normal 1 j t h I s rile o r c soiaia s is prepared r. cine i: r: a p ECMAL 
EDITOR. The EXEC OT 171 -111 read :ctji£t.:s frcr, the'jcb frle rnril oil rf fi> 
is reached or a a error is eaccaucarca « Co mm a no s s;.ouig appear in trie j o o rrle 
just as they would be ryped :roip the keyboard 5ctb built-in and u:si--' ief ired 
programs may be executed list, rhe jc&-file ''scrips"' . 

Example : 



JOB SCRIPT! • J 



will cause the EXECUTIVE to read and execute the list of commands on the file 
SCRIPT1 .J. For example , this file might contains 



FILL 4000 470C % sere memory segment 

GET !! MYMLSUBS ,J ; Iced special machine language subroutines 

MAINPROG | load & run my PROMAL program 

DELETE TEMP JUNK i get rid of unneeded scratch file 

PR0G2 >P ; run x/ second program, redirect output tc ~: r i r t e r 



The EXECUTIVE v;ill cttCoipt to execute a, II fire of these commc.-Kh. aLic 
accepting tug re CGHi!r.an5s from the keyboard = 

When PR0KA1 re frrst brcted rp : it looks for a specie 1 101 file or, yo.r 
working disk called 3€<)1!S€EIP1; c J. If it finds this fiie # iz icill execute rhe 
commands on it before accepting commands from the keyboard* You can EDIT the 

BOOTSCRIPTc J file to do whatever you wane For example, you may want to change 
che Commodore screen colors with me COLOR command , change the function key 

definitions with the FKEY command, or execute a certain program automatically 
imen you start the system. 



If no BOOTSCRIPTc J is found, the EXECUTIVE will execute an FKEY command and 

a DATE command by de faol 1 7 tc also* ay the function keys and prompt for the 
date e If you do have a BOOTSCRIPTc J file and want the prompt for the date, you 
should include the DATE command (and the FKEY command if you want) in the 
script c For the Commodore 64, you will need to have the file DATE.C on disk. 
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Supp: - 5 - ' pared ~ file :*\_1*- „ ? . ] --"hich looked this? 

EDIT ^ . : 
DELS" I 

coMriu * i ci 

UIL " - 

\ 1 iii^'ijL/Ainc u 

Mow suppose you use che command : 
JOB 1-0 = J .4 Y PROG 

The -* r i _1 ;s that PROMAL xill execute t "~ . .1: „1 zing commands % 

EDIT MY PROG* £ 

DELETE MY PROG. I 

COMPILE MYPROG L=MYPROG~ L 

ULOAD MYPROG 

MYPROG TESTDATA, D 

Each occurrence of \i ^as replaced with the first arguraer.L 'a c -:e:. t :-s fil£ name 

DO® J) as the commands were read • 

cess 

la Comments ma v be inc 1 l-G-^ G 1- Jet Tile. ;: j 3 e d e d by 11 ; 81 • 

2c The 11 • J" mas : be explicitly specified cr? chs JOB command . 

3 . A JOB commar-d iray net appear in a JGB file script, except as the last 
command in the file. You car, nake a job file that "'loops" by making the last 
command a JGB command with the sain a filename* 

4 . A runtime error or any progi am uhieh exec ices the library procedure 
ABORT will terminate the job file sad return control to the keyboard. 

5* You may execute a JOB file in the Workspace by typing JOB W. Of course 
you shouidn f t use the Workspace for anything else at che same time. 

6. The \ character is the "pounds sterling" ( £ ) key on the Commodore 64. 

?• Don': pat any cornea nd in che JGB file that nzLl require snapping the 
disk the JOB file is being read from ^soeh as a one -drive copy} 

8e The JCB file uses one disk buffer- sc yon may not be able to execute 
seme f i le-incens ive command from a JOB file ?<hich tfcrks fine when executed 
directly f rem the keyboard. Copying che JCB file tc the workspace and 
exec a ting JOB W may alleviate this problem • 

9. See the PAUSE command for a csa fui command in JOB files e 
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Set write-protect for LOCK 



t OHLY 



#u _ i i - •? . . ; i r^ " ~r . ir'Trr dLTi, - ~ - 

Jr. . ;•• ..x^rir^g 2 11,,-- or/*i; provides pre cac c ion &garti©4. i^aa^er teni deletion o~> 
t., ' r :ics _ : an ~ ^ ^css -c'~ ~ : 3 :. " rrjf.s from hrstire *;<=srs- : software 5 : 

I^orj -. : ... .. ':. y f orrna _ _ rrg £ crsr ? r>c: cces it pr-:7£t: copying use c£ the 
lii the ~r„LC3 Technical Reference Manual for mora dacsils^ 



MACEO — la fine Macro String — 

MACRO String [ String : c - ] 

The MACRO command allous you to define macro substitution striags ( in the 
same manner c.s Lc dsscribec for the JOB command) , which car* :e cs^sd 
irrteree t ively irstesd of in a JOB fi]e c A macro allows a scring to be 
substituted for a *~ . r o -charae ter abbreviation in an EXECUTIVE command wher. it is 
processed, T"e rr-rr character abbreviation consists :f the backslash charge tar % 
' q- e c •:• rr 6 seerlir-g" key on the Commodore 64) followed by £ number from i tc 
. rr drcc r rr.g rhirb coring is to be substituted, The MACRO ^ounia.id defines the 
.- , i _ 1. ; _ 1 . t_ ^"i-^irgb t>- be used in subsequent commands . The rrrst ZTgnment 
vi. 1 >: £■ c I ? e a \ 1 , tire second argument \2, etc • 

Ex amy - ^ - 

MACRO / £ 3 7 E L/ M Y P ROG 

After this command is issued, then : 
COMPILE \i 

will be processed by the EXECUTIVE exactly as though you had typed : 
COMPILE /DEVEL/MYPROG 

Example 2s 

MACRO 2:PR0CESSDATA 11 10 100 200 300" 



If you then type s 
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PROMAL USfc 



EXECUTIVE as; 



i - Ihs :i- Z 10 -.cri.-.;.: is ,:5, r ^^Iarly hanv *. ^ needed 

• ~- c"t ~ : ' - ; ' - . : '.net ion key ~<-Il:i \ - ' i used 

Iiji-^ fur*;. :ior. ley :*of iri :ic:is o 

3- I^c^c - c . "r:r?s tpv r : £ny length which "-"I - 1 :'~;3 -?re ' ir.s £3 the 

MACRO command . They may not be ues ted . 

4. A 1GB command or another MACRO command redefines ell nacres o 



MAP — Display current memory sap ™ MAP 



MAP 

The MAP command is used to display the load addressee e - any programs in 
memory , and a summery now memory is current 1? e1 located • The actual Iz mat 

of the HAp display ^asies somewhat depending on the memory organization of the 
computer = 

Example i 

MAP 

will disci? y the current mencry map - If no programs have been loaded ye c ? the 
ms.o should CMp-ar aisilar to chie ' ihe actual addresses may 1 i If e::\ § 



OBJECT PROGRAMS 


$2900- 




i j 


FREE SPACE 


$2900- 


-8DFF 


(25556; 


SHARED VARIABLES 


$8E00< 






EXEC. /EDIT SPACE 


$6100* 


-8DF8 


( 11520) 


TOTAL SPACE 


$2900- 


-8DFF 


( 25356) 


ACTIVE WORKSPACE 


$1200- 




(0) 


FREE WORKSPACE 


$1200- 


-5AFF 


( 16688) 


Commodore 64 






OBJECT PROGRAMS 


$4F00« 




(0) 


FREE SPACE 


$4F00« 


-98FF 


(18944) 


ACTIVE WORKSPACE 


$9900- 




(0) 


FREE WORKSPACE 


$9900- 


-A0FF 


(2048) 


SHARED VARIABLES 


$A100- 




(0) 


EXEC. / EDIT SPACE 


$A200« 


-CFFF 


(11776) 


TOTAL SPACE 


$4F0O* 


-CFFF 


(33024) 
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FREE SPACE 



. : . 12 zz z=,±. f z- 

laditional programs arid 

£ " i f e : '~ -j I : ~ r z - r -t ' ^ o 



- - TV- -~ L-c-; - ( r.- ( 4 s- - 



K r z- 



■ ■ ■■■ ~ - 



f C ^L A. L _ DrfLT & £ £ C r 



rrcgr;--3 -„ay 



additionally use the EDITor space if needed (described 
in Chapter 8 of the P ROKAL LANGUAGE MANUAL). 



ACTIVE WORKSPACE 



Indicates how much of the T ~o^hr3p£C£ i : ; c-;rre:tl; in 
>^se u A >;o CLEAR comma iio. r ^ ± _ sec _s ior che 

L ~pple " " ; The Workspace s r£rr;£i£er a "urrilisry 
, Carded, memory. On the 'xirnoJc;£ c- <? -re v-Jorksp&ce may 
i^"-e £ 3 ^ :ogtsr c aa £ -ed {che contents are 
maintained ) » 



FREE WORKSPACE 



SHARED VARIABLES 



EXEC r. EDIT SPACE 



TOTAL SPACE 



spe:€ ; Th: 



" ': unused p*~r:irr cf ~ ~ r Work- 

:an,d 2 an be used zc zlzz:: this value. 



Indicates the space allocated for un-lni tiaiised global 
£;r i ab ies (arrays and reals) c These variables are 
allocated et the cop of available memory, 

This la che spz.ee occupied by the EXECUTIVE z-r the 
EDITOR, cr by a users prog rare, or variables if needed • 
The EXECUTIVE and EDITOR share ':he same space in 
memory . Only oae or the othet (ei neither) is present 
at any given time. For the Cc-imiodore 6' c vrhar a program 
is executed , the EXECUTIVE is copied zc z\% R^i under 
the ROMs and the EDITor (vzzlzz was under the ROMs^ is 
swapped into the --a rated space. Or. e;ci : < :hey svrap 



again • For the App" 



ccpias cr rhr EXECUTIVE arc 



EDI7G3 are kept in the auxiliary 64K RAM bank and are 
copied into the EXEC o / EDIT space as needed. See 
Appendix G and Chapter 8 of the PROMAL LANGUAGE MANUAL 
for mere information. 

This is the maximum amour-: of space presently 
allocatable for PROMAL programs and variables,, if all 

programs are unloaded; (and, for the Commcdcre : if the 
Workspace is cleared and the EDITor* s space is used, as 
described in Chapter 8 of the PROMAL LANGUAGE MANUAL) • 

After several programs have been run, the MAP command might produce a 
display that looked ©ore like this : 
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PR0MAL 1 



-rz': C ' I 

/ i- 25 CHKSUM 8FAF 



object pROG?--i:c 11^ ^:-::f ~ '20-' 

FREE SPACE . ; C^Lr: 

shared varl* 1 1 r 1 ncei^rrr -'r::* 

EXEC • / EDIT -1,^ t~:~~ :=r T^ V- - 1 ~ 

TOTAL SPACE ^ > . 

ACTIVE WORKSPACE $1200- \2] 
FREE WORKSPACE $1200-5AFJ (13588) 

Commodore 64 

FIND (PRC; 1/ £.,• C5 CHKSUM 5527 

CODE $4F00-50FF, VARIABLES $A000-A0FF 

CALC (PR^ } 3 '24/85 CHKSUM AE67 

CODE $5100-56FF, VARIABLES $9F00-A0FF 

OBJECT PROGRAMS $4F00-56F1 I" Z^8) 
FREE SPACE $5700-96FF (15384) 

ACTIVE WORKSPACE $9700- 
FREE WORKSPACE $9700-9EF 57 (204 8) 
SHARED VARIABLES $9F00-ACFF ^312; 
EXEC./ EDIT SPACE $A200-CFF? (1x776) 
TOTAL SP^CF $4F00-CFFF '2 3^2--; 

This iisplc; shows t-o PROMAL programs present in me~c r y . FIND and CALC* 
Tr« Una scarcing wiLi 'he name cf chs program shows thai it is a PROMAL 
program. t u c date - as complied , and the checksum which the EXECUTIVE uses to 
vei if y ..he ictee;: of -he program before exec^'ho.. (describe! ii, the GET 
c o rr.TTi a ri c y © 

In? line beginning with "CODE 11 scoi-a «he starting aad ending addiesa cf the 
executable code, and the address range cf the ariat les • It ic normal fcr 
programs to have overlapping variables allocated, which is why this area is 
called i: shared variables 11 in the summary „ However ; the variables nay alsc he 
allocated immediately after the code portion, if the program had the keyword 
OWN on its PROGRAM line when it was compiled (discussed in the PROMAL LANGUAGE 
MANUAL) o 

Memory is always allocated In pages cf exactly $100 bytes each (256 
decimal) . This is *-;hy ail the address ranges start with $xx00 and end with 
xxFF 9 Therefore even if a program is only a few bytes long, it vill still 
be allocated a whole ?age See Chapter 8 cf tha LANGUAGE MANUAL for further 
informal: ion o The SIZE command can be asss to determine the true size of a 
program to the exact byte . 

For the Commodore 64, notice that the Workspace has moved slightly to make 
room for the new shared variables. This will not affect the content of tiie 
Workspace, which is maintained by the LOADer * 
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Motes : 



- ce . . , r ^ :,r:<r r\ .^r / . ' : \: z ;> . - • ^ .'. :s c r _rrr if :,i^3i 




I- If you GET **he 4p?ls c^rrilsrr i; "ill net show up ia the memory map o 
This clears because lis ccxpiler ?'ill re i—rrsr ic rsly unloaded from memory ^f-.er 
i is leaded to make rcoi for he EXECUTIVE, wh :> c r overlaps it c This is e£ nc 
pe.~~zizu.La-V consequence, except :hat you must have a copy of the compiler or,. 
ii ~h if you wa - : 1: run it. 



ianSrJME — Create a new sub-directory ™ SiEWDIR 



SlltMt. Name 

The NEWDIR command is used 1c create a new subdirectory called Name. The 
name should be a legal Pro DOS sub-directory name. A ,f / r will ue added to the 
end of the name if one is not specified. If the name does not start with a " / " 

character, then ihe current specifier name vrill be appended :. re current 
prefix. 

Example i 

NEWDIR MUSIC- ; Creates new subdirectory /MUSIC/ on current prefix. 



NOREAL — is-iowe real number routines — NOREAL 



NOREAL 

The NOREAL command is not normally needed, but allows you to discard all 
routines from the P ROMAL runtime software and resident library which support 
the processing of REAL (floating point) data. This adds approximately 2o5 K 
b > t e s of additional available space for editing f compilations s or other 
programs c However, you will not be able to successfully execute any program 
which makes use of REAL data (the EDITOR and EXECUTIVE do not $ the COMPILER 
only uses REALs if the program it is compiling uses REALS) c 

When the NOREAL command is executed, rhe EXECUTIVE will first UNLOAD ail 
programs from memory . It will then move the hot torn of available memory down by 

about 2.5K« You may then resume normal operations® 
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, i-" ■-. .: :.. c : c .;. :_ tr^p'.:: , . air ^r: i _ . - 3 



when you boot up < 



is 



'v: §c*. eiih^c zZ zz^&z ^ .^ssigce , il ir Z ic a : : is rh^ •: /on may have 
, £ z-ziz-Lc. rr.;- .n i;ii 1L1,Lc :Tjar hi— di: carded REAL 



RUNTIME ERRORS ILLEGAL OPCODE 
AT xxxx 

*** RUNTIME ERRORS REQ # D PROGRAM NOT LOADED 
AT xxxx 



PAiSl — Pause in JOB file — PclSE 



PAUSE ["Message"] 

The PAUSE command is norms lly only usee ia J?B files o When executed, it 
displays the text of a message enclosed in quotes and then watts for a carriage 
return from the keyboard. The text of uhe message mast be enclosed in double 
quotes o 

Example s 

PAUSE "PRESS RETURN TO CONTINUE. M 

When executed in a JOB til*- cms --ill c^use an: cispla»» r, ?jj*SS RETURN TO 
CONTINUE" on the scree:* If foe press RETURN, tr.s job will continue with the 
next command. Al terns Z ->slv : ycu cccld press CTRL- SIC? ( Icrrrodore) or GTRL-C 
'. _\opie s to abort the jcb ac ch is peine in the J 33 f i Ic execution. 



Copyright (G) 1986 SMA Iiic e 



Rev, C 



PREFIX 



— Set or wiew default path 



c 'ill :0 '. ... z^z~c^~i': fil-c , = ,< 1> ^ „ riHIZ ^^n^l nict ut 

srr; zc.:: z 1 :; pl.pT end :r -.€n; p?;n ner.s If a 1= opacified s,€ an 

argar^r.r ; l s V ale - i£g< _ p~~^ r t £fu-= .scHicitg and e;.cir*g r -ich / char- 
accsrs; iris f ; :i is ccsc of iszi ;38l ;c ealset € ditf-re^t rlshe i :c3 „?roDOS 
Vo 1 ume ) :c: subsequent Eeci^n- The f g rr> PREFIX * "-"ill c hang h the pathname to 
whatever tie volume naii is icr ihe d i s c e • ... e La the c~i :e willed 1 c- : zed up 
PROMAL. arid display this i£r:c , This forx is most cfcert used afta~r changing 
diske „c«s z 

Ex air p ; e c ? 

PREFIX will cisplay Ins current , £th name, for example. 

PREFIX * upases z\a cu;a:^ pi^fir : :; ir e volume in drive 1 

PREFIX 2s s^_s t^.s currer,-: prefix , o Mia vc_^e in drive 2 

PREFIX /W0RK1/ sars the cur-sal prefix to U»CRX1/ 

PREFIX * 6 1 sees che current pre fix :o s 1 z t : drive 1 

If Pre DOS can cot fire? a diskette witn. tie specified volume name, a DEVICE 
NOT READY rc - --ill g_ _r: t '1:. u ;re the PIE? 7 !.: - CLC^&hd d^^mine 

the volume cf £r„ u^l^cin d isks t te , Volume narrss s i ~ 1 i< lip £C signed 

when the g is ice tie is f ciuioic Led 

IMPORTANT s Icj Id s ---e a PREFIX - , i - 1 - ~ ■ ■ ~-:^Q-ln? 

diske ices ~ Otner ? ~ise ; PrcD-Jd not oe £jle irnd your commands :r ilies, 

because the cur::£: c :-r ~ f ix ? :i 1 1 sd; j : e Ida removed volume name • 



QUIT — Quit rSOMaL — QUIT 

QUIT 

The QUIT comtr£ "id exits l^zr Ids ? RCMAL system. The workspace will te lost. 

For the Commode r a §4 s QUIT resets the computer back to its power-on status 
in BASIC. You map ±ct re-encar FXGMaL except by re-loading it from disk. 

For the Apple Ili ddll rill cicigs :g 40 column mode and prompt for the name 
of a ''prefix" • Sneer ihe r.aire z ' the desired system to run, which must end in 
11 . SYSTEM". For exanple, zc rur 3kSZZ y you might enter /WORK1 /BASIC© SYSTEM, 

Example s 

QUIT 
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lEIJL^ Vl~Z\-~ Newfile 

Trie IfJAME command 1.3 .is~r. aaauc f 1 1 - ^~ 1 -~ * t 5 : ? .gume-^' ii 

the er :lr§ f rl~ name ar.d ::hf r^c-nd is wnc n«r" f ic rrirc .rr-ir^d • 

Examples 2 

RENAME MY FILE YOURFILE 

changes :he ;ile r?ned MYFILE.C to Y0URFIL1 C 

RENAME DATA! . 1 7 TA1 . T 

changes the ex teas icr : 1 the zils s 

For tre dcn^odnra n-PRC:-rl filer may be renamed by enclosing ' :b fr^s 

name (case sensitive) in que tss for examples 

RENAME — _ . . OG" "OLD_PROG' ? 

Fcr :he App-ls 1 path name can be spec i fie i fr~ z'ze cIl. Mis, If you 
wish the new name z rc c 1 are s. file ai;tansion, enelosa it in c^: res „ rile 

names without extensions should be enclosed in qeoces^ Y~ '.: may rarEce c 
directory * ir: c>o;eS/ lemembe*: _~ change the PREFIX = ::€; you dc frr :an 

rename a mime rnr~ ! :r quote? r no ":r filing # / # )» 



SET — 8n£ s^^cry £6 dress to value — SET 



SET Aacrass 7~lce [ ^ c] 

The SET ec;:;i£nd 12 used ic install raises in nencry. The first argument is 
the starring edcrasS; 11 hei, The secede (and rctierally additional) arguments 
specify the ralres z c be installed into r.er.c ry ir sec je nee • Each W&lae 
argumei: ran be : 

( 1 ) • A z y z e specified in hexadecimal 

(2)o A nerd greater than $00FF specified in hexadecimal 

. 3 ) - strlrg tc be terminated by a 00 byte, enclosed in doable quotes ( f *) 

( 4; e _~ spring ere losed in single quotes ( ' 

The difference between (3) and (O £bcvs is that if the string is enclosed in 
doable quotes ; 5: ), a 00 byte terminator 'rill be installed automatically after 
the last byte cf :he string, but if it is enclosed in single quotes no 00 

byte is eereeo 
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by the MAP command, 
SET 54B0 4B 

S54B0 to $4B. 

511 5 7 l i -Vr2l 1 l^rt 

b f~ c ? 1 c 5 t ' c r» > 5 1 02 " ■: "21, 
:; £01 .'r^ctst rord ^e!:j3> a 
the 1 ,. i; ~c J d £. r ; r t a f L . . • t z u 4 

^ -j « ^ - : . -- 

irstEll- fi-a sr^rtirg $t fd~^" , lewer cass ir'rter? £~e ii;t changed to 

upper case) 

S22 -BIO "Bye now" 

installs the specified string s cart dug £t $4BIC$ and adds a $00 byte after che 
last cnaraccer installed in memory (cha $00 byte is used tc terminate £ string 
as defined by ehe PRGMaL LANGUAGE MANUAL). 



SlES — Display program size — SHE 



SHE Filename 

The SIZE command is used z z displs) the memory requirements zz a PROMAL 

compiled program without actually loading it into memory . The argument is the 
name of a legal PROMAL command file The EXECUTIVE viil read the header from 
the file and a i splay the pertinent information in a f c rm similar to the MAP 
command <• 

Example % 

S12S BILLIARDS 

will aispiay the load requirements cf the BILLIARDS „ C file "ithoat actually 
loading the program iuto memory . The SIZE command display will be similar to J 

BILLIARDS (PRC,) 5/21/84 T - 7 ER 2 
CODE $06P: , OL 03 7ARS $0060 s $10 




-Ci :.c '^.i ?S~lr :: = :713 tc r^S- -rd 85704 

? t :;~ ed i -;he 5 ;s^ktr" c 5 " 1 t roressor c rder with 
- „ 1~ - -"-^ c c. ~ .., r J z £ ^ .t. r e r 5 3 c r e 8 ^ 
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because the EXECUTIVE has not loaded the program. 



TYPE — Display file on screen — TYPE 



TYPE Filename 

The TYPE command is ^Sci a a diaala? 1 tha cci"€i,;s a: a tS2:t fh Is c: bctiree 
program on the scre^a . I; -aa a l~ a :s jse-' ":c a_spl ay aor.leaa? c: «~b^ 

Workspace. Out;;-- " "a: a Is aafaaaaaaa aa a a:: Vaaa L -;aapa" ^e~~aaa sa^aa 

the printer. The ccgumeac is cae name of cae a.s._e c a ^a to a a ayped • 

Examples § 

types aaa £al- 1 I • : D • S on the screen, 

TYPE MY JOB. J >P 
types tha fila MY JOB. J on the printer • 

TYPE :• 

types the standard laaaaaay ' a aavice) - a. aha screen* 
TYPE >? 

turns your compu" a a aa:: ? i aleaaranic corre : : lag ay pewr i laa c a!1 litres , yped 

on the keyboard .ail", 1 a : ad: put to the printer when RETURN as typed To 

lerrainaca aha command type 3I1L-Z, which indacaaas 'end a f file" 1 from the 
keyboard . 

Notes : 

Id If yoa attempt tc type an coir.pi led program or ether non-text file ? it 

"ill display garbage a a the saaaan. This aan happen if yen forget to specify 
the " • S' : extension on a he filename t a as ayped • 

2. On the Comodora 54. yaa -nay alc^ a ^YPE display a awn by halding down 

C T !xL ? Ya a zaay pause the display temporarily by no id in g da an STOP. You can 

abcra aiaa acxxaad by paaasaag CTRL/ STOP. 

So Ca_ the iia>ple Il f you may taraparar ily halt the display with CTRL-S, and 
aaatir_:a the display ~~i :h any k a y - CTRL-C a T ill abort the command • 
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UNLOAD 



UfflLOAD [ Comma nd name ; 



am , 



r „r ~ z _ " - ^ c 1" : r z : z : z- ^ cil::l: .. ;. . c - r a i ~* r " z * - ~~ - . . ' r ~ - ' 1 r 1 ~* t 
- - & ~-~-c«.-l~ f_*r lr~. III7 ^ z, : i ^z _ ■: ... "1a" f LI ' z ta::^- - ~' .. i : ~ ^ 

: . _ ^ *. jc _ 



LUU < 



. - ••• • ••• - t~ ; y- --G""i.?r,c ";^9 ~ ; -iorr_i r "~_1~ 7z " z~~ ? z ~ z^ 7- ■■ r--' 1 

■ - :i;a; „ : ~ _ e zz " z ^---c z " ~ 9 r =. n ? - s'^-g rf in sr^ r nr-"? ~~fi^r? ~* 7 r s "'2? 



are unloaded, 
Exam ic * 



- RfiQ 



remc~es che BILLI-^DS program from the EXECUTIVE' s command 7isz : freeing up 
eerier y rreriously allsc-stsd zz zz Izr other programs • Toe MAP comma-ad car. l:s 

r se-i t g zz 1 s o 1 a ♦/ t ha re s r 1 ^ 5 : 



T f- - - 



lc ~\,er c program is unloaded s tna memory it occupied is not cleared or 
altered irk any ray. Iha space is merely deallocated , making it available for 

ether pr ~grnm as they are loaded. 

2. If two leaded programs have the same name , only the las : z one loaded will 
be unlc if z.± Iris situation arises rher different cbyaet file rases were 
loaded T rhieh h?d .; za s * me PROGRAM name when compiled. 

UELCOST — Unlr-eh £ fils — UNLOCK 

r-LOCH filename lo^j 

Tr e Ui\ T LCCK command removes che rri ta-p rc ca 1 t status from a file previous ly 
LOCKeco Once UNLOCKed , the file can oe deleted ; renamed r cr overwr i t ten 

File names without an extension x,ay be unlocked h y enclosing the file name in 

quotes • 

Example § 

UNLOCK m: SOURCE • S 
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:T iize ; Tn.r ic/i- is £- ;. 1 1 ct 1 ? :r >iz:i:^ ;4 only 

or 

MS CLEAR ; This for„ : i ~ r^rLlai/l^ j.. „. :h ,::i; :.irs. 
Description : 

The MS command is use J --a c :^_/e ..<r ^ _d c.r. Workspace ( the W device 
in -memory f il : Oj: ~: ui?:5:: :ci;ai::. ,„ Ice jire ~ ::-rri c bjr Commodore 

C-il;. has an argr^ii nhic . i -ratifies the desired Workspace -f i^e in hex bytes ~ 
If the value spec i ilea is iess ihcr; $£C3- it is assumed to be in hexadecimal 
K— byte*; liib'esd- I r t'*e «i^e ^quested is larger than the remaining aval lab le 
space, MOT ENOUGH MEMORY will be displayed. If tire ACTIVE (in use" Workspace 
larger than the requested Workspace, no acti" : ~ ^ e sr^ tie - ?5^; - 

11 ACTIVE W IS LARGER, ( WS CLEAR WILL EMPTY W) " will be displayed. 

The second forn is used to clear the Workspace c The memory content of the 

Workspace is not actually aitared : zzz the interne! r cirlers need :c rx^iprlaie 

the Workspace are set so that the active Workspace is f; & 

Ex air. " i6i i 

WS E 

sets the Commodore Workspace size to 14K bytes ( $E times $0400). 
WS 1800 

sees the Commodore Workspace size to $1800 bytes ( 6K bytes) a 
WS CLEAR 

els ars ~he act ire T7 crks pace to without affecting the size cf che Workspace, 
yczzz for l^ncsedcrc 

lo The default size of the Workspace is 2K Dytes ; 2048 decimal) , The 

location of the Workspace varies as programs are loaded and unloaded • The 
EXECUTIVE maintains the contents of the Workspace as it is moved around in 
memory. The COMPILER and EDITOR rill use the Workspace for suffer space if it 
is completely empty. Therefore you caa EDIT or COMPILE larger programs by 
issuing a WS CLEAR command first (See the EDITOR section of chis manual for a 
more complete description of the EDITOR' s treatment cf the Workspace). 

Notes for bpislbs 11% 

1 • The workspace is maintained in auxiliary memory (the "other" 64 £ cf banked 
memory). The Apple has a fixed size workspace of about 18K bytes. 
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* _v - HI ~ - jl ^ . - ~ ^ - - . .. • . . 

. r : i - r ic :. z r . n : i. i - 1 1 ;ie : ; i ~ " i - y 

* In s e „ • pe-over mode. 

* Global search and search -and -replace with fl * v e ti : 

* Block copy, move : iarete- save, and recall. 

* Semi -Au tor? a lie Indentation suppor t f«m I10MAI re grams . 

* Fast 077 " .on • 

1PXTC C : f l-cded int-~ ni-iry s.utCT*~" 2*: ^hen PROM&L 13 turned rr = 
and is 2crma] 1 ,; ' £ permanent oar: of the PROMAL system in memory This msM.es it 

va:-" 1 ifrnaiileni tc c^e, rrii^n iic EDITOR ic- nlwiyE instantly dvnils. . le * 

SfTi£i»G iS HDII9R 

IrcK lis IIECUTIVE, you may er:sr irs EDITOR tilth the EDIT command r : : : t'r e 

yill: .illename] 

i IllsiiSsa is 1 : . t 1 nal argument specifying lie name ci lie file _c edi t 
„i .,n~. Jliaaisss is or, - .is 1 ; ihe EDITOR will use lie file in ens Ucrksyeiey if 
nry o Otherwise* & nev: file rill be assumed s If a Filename is specified and 
' 1..1 c ei;lit . tne £11111 rill stnrt £ n~- " ills by that name . The EDITOR also 
^ciiitci ^^£1^ file enirnr^lij :f 83 ^ S" , :: it : 1 ic: necessary to specify 
the te>.i _c.i when enteritis ihe file name . 

The EDITOR begins by "signing or/ 3 ~ If ne- "Lie I? eing created; I°e 
:1ii1e" '-i°. ' 11'" 1 e visible long enc • : ^ = 'ir.?-:^ the screen n T lIl ce 

immec i s ie ly lenred and the cursor no red te t u e rpper left-hand cerne^ cf i.ne 
screen I?r yc- cc start your new text file or prcgranic If you are ed icing an 
erecting j r _- message sHLll be ^Isitle mill trie tile has been Icsred Intc 

memory s 

TIE illtXZ IISrrL^X 20RMAT 

For a new fils s the EDITOR ;#Iil show an initial display as shown in Figure 
la , For Commccere c^y or 11 ; for Apple II) below. 
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COMMODORE EDITOR SCREEN DISPLAY FOl A NEW FILE 



. :: e= i 

F1=DEL Li F3=MARK F5=FIND F7=HELP 

?2=Ii-3 LM F4= RECALL F6 = CHA*?GT FS^UII 



FIGURE lb 



APPLE Zl SUITOR SCREEN DISPLAY FOR A NEW FILE 



; LINE = 1 | 
i .=DEL LN 2=INS LM 3=MARK 4= RECALL 5=FIND 6- CHANGE 7-HSLP S=QUIT \ 
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srsa : : r text area *'~ill ~. :.. ': rrr. ; ': ~r s " ty " r-r ' 1 r y one tire !"e nare r : : - :?r 
elf i timet tart The lines that st_:Il cff the ttr of the 3c;ai: t &ra rx: lest 
bat are merely no longer vi sib Is 9 If you move the cursor ..„c beyond the top 
- ^- -~ ^ ; ;be iez: area --ill scroll cairn 1 line , until yc r stcr riorirg the cursor 
r: : • reach the b spinning rf the fils c 



If the errs or s tops advancing as you type and characters overprint ci£ on 
top ct the otrar, ic aeans that either (1/ you have reached the maximum line 
size so to no^e characters can be entered on this line, or (2) the edit buffer 
is ccnplaLaiy filler 

Xr the EDITOR., you have all cl lha editing keys available to you that were 

in the EXECUTIVE j plus some additional ones. These keys are summarized in 
Table 5 be lew. 

The best way tc learn how to use the EDITOR is to EDIT an existing trie 

and experiment with the various keys. You will not alter the existing file on 

disk unless you spec i f leal 1 y elect to o" T err«rite ths e> Let lag file rhen yea sxit 
from the EDITOR, so you won' c do any harm, 

EDITOR FUNCTION I1STTP 

The funr t Loi: keys operate somewhat aLir^ eatlj li. cle EDITOR than in cae 
£XZlUIi l7 5h Trie meaning cf each of the tjrxtici rays is a 1 rays shown in ths 
status area of the screen. Under sope cireasistanees s these function key 
ff lege rds " ^iii change during command processing « to sllc** .Tier a than a total of 
8 pes sib Is actions. Some of tne function keys perforin En operation 
immediately and some require additional input tc be typed followed by RETURN, 
The action cf each of the function keys is described in the following sections. 

For the Apple Il s function keys are activate by holding down either Apple 
key and pressing the desired number key, 

TIE HELP DISPLAY 

Pressing the F7 (HELP) function key will temporarily erase the screen and 
display a screen showing the meanings of the control keys e Pressing RETURN 
will restore the normal display. 
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to^octere Apple 
Key Key 



RETIF 



1 . 



DEL DELETE Replace the charac "ar Is ft c c lie cursor with a blank 

and backup the cursor oae r :si-::on • fell I "pull back" 
characters to the rignt orilv If in "insert mode". 



IMST 



1-:- : ir "insert mods"' a; 7 -*-h a rat -? - : . ^ : . - ^ ^ .„ 
~ v i ? " be inserted beirre tha nharf c <*sr f:s ^* 

p 7 c ~ "- r.g any er i s t 1 a 2 t s - : c c the .: 1 f~ ~ ~ Irr 

mode by pressing RETURN or any cursor key. 



llelers character with pu lib ache 
uader the cursor and pulls aay .: 
Isf; co fill 1' <rhe gap • ua the 
Is locate! above the CTRL 1;?" , 



.lasers 5 zza cr^rtcrer 
snaicirg text to the 

this key 



— > 



Cursor right- Moves the cursor to the right, without 
altering the character under the cursor c Stops at the 
end cc the line • Pepeats automatically after a brief 
pause if ireld cown , Cn the Commodore d^- 5 advanc ing 

beyond column 40 will cause the iiae cc temporarily 
scroll left s allowing editing beyonc. column 40 • On the 
Apple : line scrolling tsgins at column 80. 

Cursor lafto Moves the cursor to tha iefto without 
a lesr ir.g the character under the cursor . Stops at 

acioira 1 c f the line. Repeats autorr V,a*iy c Iz a : ? 
r r e f rarse if held down. 



CRSR up up arrow 



CRSR down down arrow 



Cursor up. Moves the cursor up by one line© If already 
at the top of the screen, scrolls the screen doivn to 
back up by one line, until the beginning of tha file is 
reached • 

Cursor down. Moves the cursor down by one liae. If 
already at the bottom of the text area, scrolls the 
screen up to advance by one line in the file, uracil era 
ef file is reached. will not advance beyond erid-c r-£ils 
(use RETURN to add new blank lines at end-of~£ i^e'" ~ 



totes N/A means not available. CTRL X means hold down the CTRL key and press 
X. 
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iOC illci 



HOME 



C 

CTEL 



on 



CTRL \ \ = :: rr..:.. J 1. r-. e - . cV~~r..-i c i ^ i the 



■ . .." ~ _ .., 



CT1L- T L ,rrrrc t last :^rs::s: in IraSc Moves the cursor to the 

;ii£rs;"-; -frer rhe i££': rhEraeter on the line, without 
s - '; * r - t '" e in^ 



•rtrt font* 



CTRL * CTRL F -;r»c firsr ^har^rte^ " line. Moves the au.rsor r c 

toe fix st character posit ien ? without affecting the ilae 



CTEL il CTRL A Tcggls Alpha-Lock mode. Switches In c-r out cf ALPrlALOCK 

mode. It the ALPHALOCK indicator apy^ars rr-. the s ,£C.o 
c,re? , ;hen a : l subsequent Elohabetic characters to u e 
entered and displayed as upper case vher. typed 3 

Pressing CTRL A again returns to normal upper ard lower 
case alpha moo 6. 

CTRL i TAB Ted and indent e i loves the current levc : of indentation 

or in by zi-:o c c 1 urn:: s t forming a new temporary nargin. 

CTRL 1 Generally ased after a conditional statement in a 

PROMAL program. 

CTEL 1 CTRL Q dn^inoert * Moves the current left margin two columns 

left s so that subsequent text will be entered with one 
less le^el cf indentation. Generally used to end 
an indented Dlcck following a cond i ; io nal statement in a 
PROMAL program, 

S -2T7U 5 Next page. Erases the text area and displays the next 

20 lines from the file being edited, 

CTSL :? C71L ? Previous page • Erases the zex : : area and displays the 

prior 20 lines from the file oeing edited. 

CTEL J CTRL ~ Adjust: right e Moves the line the cursor is on to the 

right by one level of indentation (2 columns) and 

advances the curse:, to "he next line. Usually used 
to indent an existing block cf statements in a PROMAL 
program when adding a conditional statement In front of 
the block. 



Note : N/ A means not available. CTRL X means hold down CTRL key and press X. 
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lore -Apple 
Key 

CTRL 



CTR1 3 



i r e -3 : i ^ h i. r .1 f r 1 i i; i h •• 
f f e c - i 1? ^ i * £ c c : ci: ; 
;lrrn '-ill ie higiligm 
: :: the le i t i : c f the 



Lay , 



used 
oup of 

isi: 



CTF 



CTRL 



Norm- 11 ?e window. Re s t c- : 

pes ic ion so L c$ ^ . •-• = ? >i: 
column 1 c used to reac, s 



xi che :.:r^ci :ex". display 
^ i5,:i'c: beginning with 

a.fscc of a prior CTRL W. 



Bac - i- c -k • Erases &ry -Mc ill i jci^xnd line and 
ai:=;£ ihe las t EDITOR command entered . More can be 

type-' cter the recalls! coimreir . _ : ;.. : i i ... be edited 
z^zzrez ?rasci::g CTRL B again r 1 _ 1 recall ihe next-to- 
nics t recer-t liia sntsred 5 This can be repeated ..;r Si 
the limit of the tacftrsStz 1 ?„f fer of 25 6 characcerss 
then the display c#I 1 1 "Viap ercund" to rape, 
recent command again o 



Note : N/A means not available c CTRL X means held com the CTRL key and press 



-res^ ing ire r'l • oLL i.:*h f unc t ic-r. k%sy will u>asc the iiae v.mg c urscr ce 
on co be aele,. ed and cr*e Iii.es belcv it iiiil move up Le fill in the gap If 
you deists a line accidentally; you c an recover it by pressing the ; RECALL) 
function key followed by the RETURN key, 

Pre 5 3 1;: g "he F2 (INS Lis) f met ion key will open up a ns*i r h lank lire 

above the line the cursor is currently on, and move to the -start of the new 

blank line . Existing lines c c text are poshed down to make room for the new 
line . 
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FIND 67 



. - i • , .. • ± _ . :« t . . :.. c * 

For ex an 7 " ^ ~ 



nateiy 

- v. - - - 



7i7c, 7 o c erarcr^e ,.7' 7 ^ — r - 77s "s-c-c.c.. number the.-:, can be sa.erer 5 it 

.77t"~ ~icr jvr,; :: th e leg inning .if file- using a FIND i co^r.^r . 

You may ^lr* si:er £ - : i.~i lacemrt crst^d cl nr resolute line number . For 
exam ~ ~ c 

FIND +50 



wi 11 redisplay the text area beginning 50 lines from where you are now, and % 

FIND -200 

-i^L rack up 2 CO lir.es from where you are now. 

You may search for a certain string with the F5 f unc t ion key by specifying 

the desired string in. quotes • For example; 

FX 77 ' 1:77 7LE # 

searches for 7 he string "' 7^7 7 7" n Either single (") cr double ( ") que ;.es say 

be usee ~c enclose the string* ct must cs^cr be tn end s <, Searches are 
alimys ssde is the forward* d7iracrr£©rcc stsrtiag frssx cTie presasf: cursor pc- c v7"^n 
(not necocc^ rily at the cf t-h« scree--/ « 7f cr-e s :rcrg is round , the text 

area will be redisplayed s careers vjirh the line containing the siring, with the 
cursor cr: the first character cf the string. If the string is not found, a 
11 NOT FOUND' 1 message will be displayed ir. the statas &:°sa and the text area ril' 
not be changed. Press RETJRN in this esse tu remove the message 

You may also combine searches or. o single command . For example to jump to 
the beginning of file and then search for 'WHILE GETC , you could press the F5 
function key and complete the command ass 

FIND 1 11 WHILE GETC" 



If n WHILE GETC" is not feend, then the text area will redisplay starting at the 
first line af:er the -ICT FOUND message. In a compound search such as this s the 
screen 1 7 dlsclaj the last "successful" part of the search (that is, the FIND 
I pare in ,his c a s e ) c JL particularly useful compou&d search iss 

FIND +1 ' XXXXX' 
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*~r' '* ::v t r ; c vr~ . jccc;i^:/;^ c: „~ ? r :-J~ 1 . : r ^ill liters * 11 

prior occurrences in the . . - ~ - . ,. ... * ' - 

then search for ' PROC S~": ; ' th^r ?3-c~c*- :cr'~£rf :~ , ; " . 

SUkECM AID REPLACE 

Function key F6 ( CHANGE is 5 Lrrler the FI 11 ' i:':ivr \~y • r : /z allows 

you to change k string to a different string automatical;; - Lifca -he FIND 

c chit, and . you need to ccrrple ':s the :^ir-^arx £f-£r pressing the Je key. For 

C~L~ KGE ' SFRITEXY ' SPXY' 

.1 search forward from the present cursor location for the -string r SPRITEXY" , 

and whers it is foetid -?iil Highlight the matching string in the tex'z window and 
disc lay the prompts 

CHANGE THIS STRING ( Y/ N/C=CANCEL)?_ 

Replying with the Y key vill cause the spring to be replaced and the command 
completed • Replying ;;i th the 1 key -v i i 1 cause the EDITOR to search for the 
next occurrence of the string c and repeat the prompt when it is found o 
Pressing the C hey ril; short the comma- i ^ith the message ft CHANGES MADE 11 . 

More often ; yoa ~-~i 1 ; ^anz r o use the CHANGE command to replace several or 
ail the occurrences c f a cartels string. This can be done .:• y replying s 
repeat constant in rrcnt of the string to be searched for. Fci example § 

CHAi\ T G£ S9? ff SPi:iE>rr : :; S^?xi"' 

will tell the 2DITC3. r, replace ep to 99S :^;r:e:.c^ rhe string " : SFRITEXY" 

with " 3FXY' i 5 again saer^hing forward from the present ■:. ursc~ lit^ti?i- The 
EDITOP. v'iii pause el each occurrence, high • igat it« stc prompt? 

CHANGE THIS STRING ( Y/ N/ C= CANCEL) ?_ 

This gives you £ chsnee to :, /eto" any occurrences which you don y t want to 
change* This is very important, since the EDITOR will often "surprise" you 
with occurrences you didn't tnink of « For example ? "TEN" may appear in 
"OFTEN" , which you ^eally didn' t want to change * After the last occurrence is 
found, the EDITOR :jiii tell you how many changes were made • 
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n* - = 



>e mov^c 



viV: " ' , nn: t' = c --«-- •• - k~y "i-ini: 1 ^:> r -/,c to " 

Fl -DELETE F 3= MARK 7;-::,' 3 r 7-'V r 7- 
F2= F4= WRITE "--3**- y^— ny : 

• i . . :riim:n yo n r rn~- T iti.-- .- V ■■•■^ n o r. o i_'e ^n -ny ^ : s 11 = - Move the 

■„ usio c-j the 1*5 1 li:^ v i -:ha :mt Vic sic and c: = si IV 7 t ~7?7 £gci For 
Inrse blocks 70 u may need ... ^orcll the Afreet or :&e 7" 77 "irnnaid ~ 1 1 o c ve 
:ie ' es : line desired. All intervening lines v-ill : d n Igh lighted when you 
. '.: 1 : ; .: L ^ 73 key again • Any numb en if linis can be _n o7od • You have now 
designated ihe btocn co operate one The 78 (CANCEL; key can be used az £.r..y 
: in 1 -i cancel the. ;:iucic . You may nlso aa::' Inn 7 lock with the Insc iin - 
:: 5 : c c and then the firs.- nte 1 it doesn ' r r.£Ciir 5 If you wish, yoc can else 
ins': ireri F3 rapes mil: until you ha^e the ds^i^ed rirmbar of linn^ r ^rh^d - 
li;.: :iy:sn?:c n if 7^ " 1 . , mark one morn linn * 

If you ¥£::; In mo- e tla block or c:; ' 1.: clss rhsre in the filar ;;c^:- li^n 
the cursor to the desireo - is • $ - ion and mass 77 '7777) :r 7c ; «10¥E) - Trie 
marked b look f -"i 1 1 be inserted above the linn the :irsc r Is oi, 7he h i g a - 
lighting will be removed, comple :ing the comeaic , Copying a bloctc requires es 
much free space as copying • Therefore when mo v lag laige clocks ? you may wish 
to use WRITE block, DELETE block, RECALL block instead 'described below) e If 
:::: .... -£ii to ielsie ".ic nnrded 71i 7: , irass 71 / 771 1~7, i:rteac= CAUTION: 
nElES 7£ 77 "7477 77 ~77I^\17Lo7:7 : 71 7777177777} 717777.,.. 



If : m f oc 1 1 re s ^p-^n - n 'ce? n- s 1 i . e - 7 re - - :ns -4 , "RITE) key, 

.ic "nr: ] 7""* 17E" ~-~il.„ n:nsci in :he c ~z ins nrea : followed 1 y the cursor • 

linpleie ihe -lOTonsnd by : n i ig tnn n-ne :; ? legnl PrTTTVTl file tc receive the 
copy of the marked block. The tile ifiil In created and written 01 disk, and 
the highlighting removed , completing the command • For examples 

WRITE TEMP.S 



en tension, the 7V77TCR will supply a 11 » S" extension by defnmrcd y>n mny e, 1 s ? 

•rrite to defines => For example? 

WRITE P 

will type the marked block 011 the :::i:a r 3 7nn nay also v. T r i t e n clonk tc the 
Workspace, under some circumstances yse the a L?r oussion of the workspace and 
the edit buffer at the end cf this section for .no re information) c You cannot 
append to the Workspace, however, Bo no c try to write to the S device. 
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"js/:- r?:yy : r editor 

Function key F8 (QUIT) vll, l-£y the buffer status and exit menu, 

example % 

PROMAL EDITOR VERSION 2.1 

COPYRIGHT lb6c S'n* , 

FILE ->_5 - v { --UTO-UPDATE ON QUIT) 
BUFFE ' 585 

FILE cklf - • f > -r 



R = REPLACE ORIGINAL FILE 

N - WRITE TO NEW FILE 
W = WRITE TO WORKSPACE 
C = CONTINUE EDITING 
•BIT EDITOR 

SELECTION? 



Ih& , ^ffer size e~id k- 1~ dir - Era shown in deci&£i r'te. t J" t 1 -ffer aloe 
r<sj :&seuU to- maxi_uUu; rile size that the EDITOR can wo - _o ( - *■ .an be 
increased by unloading pre grains or, on the Commodore V- - v " >1~? ing the 
Workspace*- c 

rrass the key corres condii;- rc ^ha desired rrtirn and press 1 ZkU'kF 5, "fill 
repleoe cha original file you spe„- Hied on enti; rc the EDITOR, if airy •.„:£. :r^y 
be 5, f £.13 spa^ifiM on e^ery o:. the SITCEc too) . If co seise; 1. you 

v-W 1 oa prone cad re enter the nao.e of roe ne r ' fllsc The V rciico. "-rites ': z rhe 
r "o~*v8pace ^k" deriee^ Ir is pesri^lr I'oet tk^ TJ rr v ~pace iray net l^rge 
enough to hold me eotire irle si" red I~ "his case, yea ;_ il " be ae\ad if yea 
wish to write to the Workspace anyway, -n which case the file rill "': e tr;i- 
cated • Otherwise you can. :rrlre the whole file rr rhe disk ro ssvs it. Or. roe 
Commodore 64, when "auto-updot iag e! the Workspace y -"no -Jcrks^Eee rre.y be 
increased in size automatic £ 1 ly i: c needed ': ^ r-rld toe file 
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o; si-li?~ :r?':loT. "rec ^c" ' • ..as:; c: r=^i;„ ;c ; ,r J CA^Ceil¥T ? 

3 — c: ^ RE I U Jvls • iris i~il,. aar ^ae screea aaa returi to Ihe EXECUTIVE, 

NOTE 5 " T :-sr ~ :hc I£I7or vich CTRL-STOP (Commodore) cr CTRL- RE SET ( Appl*} . 



As a fir.?? nc^ ; PxlMAL EDI??'? 1 ic i-eelf -r:-!^ in FROMAL. We think 

that y^v * 1! "ire ,h: z cpzI 11 z u here avs- Lccgidered wvicLf.g 

v cur ov:n cgi;o,'< ,:g :: a pjccess^i ? cr siniiar program in a high-level language . 

Cbvi--:sl?"c P ROKAI car, iz the j :. 1 ; 

SCT^lGIi ??1 1?H 1^1 ^^IGi- JC- L\!S?1iC^2 €1" 

The remainder cf caa sec t ion c "r*e EDITOR sppiies r r_ 1 y to the Commode S4 3 

RELATIONSHIP OF THE WORKSPACE TO THE EDIT BUFFER 



The EDITOR uses all unallocated memory as a buffer fo" editing your text. 
The size of unallocated memory can ta displayed by the EXECUTIVE MAP command • 
Depending on how you enter the EDITOR and whether the Workspace is empty or 
not, the Workspace {¥) may or may r_c : Vs "absorbed 1 * into the edit 1 1 f e ... , 



?iish I'emcr- 



Workspacs 



tree 

Space 



Workspace 



. Edit 
! Buffer 



Edit 
Buffer 



Executable 

Programs 



i ixecu table 

S Programs 



Executable 
Programs 



Lov7 Memory 



Before EDITing EDITing with EDITing with 

Workspace preserved Workspace absorbed 
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: r .V ~-i . "1 c< ~ ~ "* :-r . :.: t h *• "1 : " :: " - qximize your 

1. The Workspace _ : - ; . 



2, 




The Marrjc^c .. . ICi ; ~. . . _r i~ _ b^ f--.it. r- . c 1 i 

i, :r„-^ "o. s -£:,-cs 1 *~ Pb? err ~" a r : a ~ila rerc --r <?z~*' '"i_i on the 

EDIT command . 

li the Workspace is absorbed y : r cannot WRITE or RECALL from the Workspace 
during tks 3DI7 session. If the session was starts: -~i th an EDIT command 
without a fiie name or W spec-' liac> ;re Workspace "ri 1 ... be automatically 
updated rher y~u quit the EDITOR 7 ~ the Workspac a i? nr ;: fit s orbed , you may 

use it li'^e a file during the EDIT session .dm: SAVEs and RECALLS). 

In any evert, ere Workspace vn^l be "en-absorbed" when you erlt i"r:E the 
EDITOR back to "he ElblGTl/g- dhe bIZClJTIVE WS command can be used tc clear 
the Workspace r olcsr 1"- teirra entering the EDITOR, 

EDITOR COMMD-}^ ib rZ, ibbflblr bibb 

The EDITOR creates and upc? :es files cf atandard AS oil .h?rsc^;u 
Ucf crtanataly ? the Commodore cracac ter -generator ROM 7 s do rot conform 
completely c the rrSCil standard. As you may know, there a~~e - -n- .sets ? c 
characters vchich car* be displayed on the screen, upper case pics graphics end 
upper pics icrrer cace. The PROKAL EXECUTIVE selects upper and lower c.£se mode, 
and this is the moce dr. at s T'.lc normally be rsai with PROMAL. The ALPHA LOCK 
(CTRL Ar feature c £ a be used c: a u t oma : i c a 1 1 y generate upper case letters in 
t r i s uio d s f i f yo a <:c choose . 

llfcie ray be times, however, when yc- r xi s nf ;^ ^ v_c adit i;. :hs rpper case 
ana graph v~£ mode . You can switch redes 1- T creasing S'-ilFT f- " -k f _ed Commo - 

dcte 'ce; • c When the EDITOR starts up. it senses tea crrrartfy selected mode 
a no. adits accordingly. Also, rher the EDIT bib? sera is cisp^r;ed : ycc nay 
Switch modes and then resume editing with tre C se „ec :ier fele^cirg -:ha 
upper case and graphics mode will permit yc-a zc enter tha various r_cn-_4.SC 1 1 
characters supported by Commode re . For installing special characters into 
strings in a PROMAL program (such as to change calces or reverse viceo) , we 
recommend that you use the special hex liberal form described in the PROMAL 
LAI\GJAGE MANUAL instead of using graphics keys ( f cr example. ' s t:2 delta ; S?2 ff 
will generate a reverse video stringy 11 Hello I *' % > a Chen yon eric back tc the 
PROMAL EXECUTIVE, whatever character set yon enterec tha SDITGR rich will re 
restored • 
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Jl.^ _ f, _ 1 1 1 I 11 ■:. /- . ,i - . • - - ZlZZ ..■ ' -,c n~ _ 1 ^ z Z _ c - ' Ohr 1 '1 - 1 -.1 *- 1 5 



" : , s~~zzz : ' . -_tn - ~ :c?r?r 'r . - :. c :: ~: -j *:/re 4 : - r . 
vr ti-^, Tc^i -. ~ZZZ^ ^ :. . ...... " . : ;.. Z ?C^zzlzz ' ■ ,. • • 



£ .-• :i : .... 1 _ _- ale; z~ e - -rl^i i::a:^t^ inan^ zziz^e 



- c " _ -•- ° ~e~~ i - ------ i — a - ~ o ' 



£• z z:zz : z:i ~ °iis oris; ina 1 text version of the 

rr:grcr ~zitlz z-z. zzzzrzzazzz £3 is cons in IJlSIC- Ihe c snails:? i zzz tic :•: sltsr 
-scarce , 1- is lei: m;:^:: ;o<- *• a :.. e^min^ 1: oz bzzz z z farther e 

^ — . c. -= ;• » -: — ~ V c c * "~ f. ~- <c< .'" ^ ■> o c- ^ .'.-*>-- £ r ~° C ~ £ - "' ~ f" ' " "> " ^ ~ c_ Z^ r~ Z '\ ^ x "~ Z ".. J, Z ' "l 

i-i'lc C n ^ c; «s. . _ ^. i. ^_ s,L" s o i. - C — _ _„ ^- Z&Z ''Cue- G Z •w x r Zli c 

Unlike the EDITOR and the EXECUTF"! zzz Zz^ZZLZ:. is ncz ectomacL-e ^ 1~ 
1 saded into .^a_^r- FFXLAL b.cts zz „ r^l* .aase the COMF III I is : 

large prograri. { d c-*j z 151 ^ i:^ Ll or.l/ .ecis: "hea you wai: :c ^^npi' c 

a new program ( re- li^-f : ' 1 r I ... : r .a -e,ll c fo:it 

STAElilS IS COMPILER 

The COilrllZR can be run from the EXECUTIVE with a comma:: zZ ;:he forms 
COMPILE ^Seurcelile; • 1^11 : zz z f i le] ] ; L^l.12 : f i „ £ ^ ; l^z] . 3'=£olf } j 

Tr ; € sixTlssi fc-~x of 'hie comma is justs 
COMPILE 

'^:r. '"II : ct: ~ ~~ =. ::urce prog - 2r f ~:r the Workspace and produce an ejcecut- 

1 ... z'"2~zl zzzzzzil zz zizZz? real.; ^ <. zi by typir.i 1^ ,.>.me • The object 
j zczzzz* <- y z 1 : v a -"ill ::ve the s a~ e fils name as the r^zne on the PROGRAM line :f 
srurcs :r:gri.r: f with a n • (l' ? 3:- zzzzz~z.c 

If you compile = program which zZzzzzy has an er is " ing ob j ec file tha 
" z = 1 : :he co^p^- ier dll prompts 

REPLACE EXISTIM1 ?il€^€i : is . C { N) ? 

Press Y and RET113: :c zeclzce 'zlze zZz zzl z - £ azy other reply ? ill. :err inate 
the coEDil£tiGn, kZz(zz a sztzeeszuZ ccxpila _icn : the EXECUTIVE vrill 
autor.at ieally unlcac ezi" ~yzs cing err- of -ihs ^ ^rpiled program from memory • 

This ensures .:hct you will always eiec::- ~ra new version of a freshly compiled 
program, net sn z 11 vers ion which might si ill be in memory. 

For the Zzzzizzic zZore 64 1 The demo ccr ile^ :an be used tc compile sxsll 

programs directly from the Workspace 7 ihezz zzsizig fee fell compiler {clhi^h £3 

larger thsr f:lis demo compiler) £ yas ^£11 ifaat to keep the Workspace ilear sad 
compile dirsetlj fr^ iisko 
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U .S 5 - 
COM] " ' 
but 



n? : 



I _ , - x me com?:- car i 
?? jm:-d MYPRC 

•ir..i udiae as the sour 



e "0" (the lu ?s~ ft oh ts :ctl:? tc -utput tha :b ject code to a 
he same na„ c _ : h e s • .h Cila 3 For exacts i 



^l^t_ MYPRC >K£.V:7£RSIGN 



fc~Li - aad Hlr ICC- £ ^n: a ~ac.=: IZ /VERS 10.- -ih ( "ota " *"e strong ly recede." i 
that ycu CcS His 3sae file nana f?a yor? cbp3'ir fils a© £3 declared ol the 
f HCG^AM hei.de? li-ae of" soaroa 'jrogrssc Otherwise, :?s EXECUTIVE trill losZ 

the FILE yoo s-,e_lf_ 1 . CisI? aam tine yen type Its :-?es even if the ?aT.€ 

program ic £** rs.a?"y ?a ran": ~ t-e?.aj.se it do?~? ??" -rxtc? ?he command name. The 

name 011 the PrZl^Ltl ^ tatene-? :? : v ~a name >iiich appears dr. ?'~e Mi? display ^» 

If you add me =t h" : up:: irr your cenn^and r a list lag ^iii be produced • 

The "I' 1 option cy imalf " 7 i^l !^ls€ the listim tc be arittsr tc £ file vrith 
tae same name bat mth s *ZL** en? ens ion . For example? 



: L4PILE MY P ROG L 

-ill ?ead hi? PIP ymdm? m :>j3-: fi'a ^YFRC'G- r and listing file MYPROG.L. 

Ic the li??mg ? ' resdy exiscs I? mil be caplaced e You can also send the 
- ^ ----- a — --^--^ f*- - ----- ^ r _ ..^ _ _ 

11 s V option is mad tc smcify a mm Ic?: r f yc ?r program for coral clonal 
mm a m? • aemmrsa ?n C-?;ar f ?i me - F Prill LANGUAGE MANUAL # 



laa final opt ioa for the COMPILE cox^nc is toe • B n option, v/hich is used to 

compile big urograms :ron d i s ^ c This option will not normally be needed unless 
you a ..: come iling mirly large programs c Tii^ 5 o~ ? ior: is cot available on the 
Demo ccT:pilsrc 1? is sssy to tell when you -?eed tc specify tne B opt ion • The 

statistics diaplsyad £t th^ e^d eta 2cr.pl la tion tell you how much of the 
COMPILER'S avaiir ols table space «as usea If <Lr..;. of the percentages shown 
start approaching a^out 90 percent; you probably should be using the B option© 
When compiling large programs, you should be sure to ^gjgggb e r t o UNLOAD other 
programs bafore ccmoil ing . because the COMPILER uses all available memory for 
its tables * For exav^le % 



UNLOAD 

COMPILE MY PROG B 



will read MY PROG. S and produce an object code file MYPR0G*C 5 allowing very 
large programs to be compiled * typically several thousand lines) c 



Copyright (G) 1986 SUA ItiCc 



Revo C 



: - c i r zr. - It ~ £' J ^ 1 d . ~ * i _ . 1 j e r e 1 c -a c c r f ' cr: i I * *- r r c ~ : - z j. r.re d t ^ , 

'-«T ; - - - ^ z l z 1 c " 8": -r CT C -7 '." . *• " ~ ; • ; 7 • ~ •• *• - 77- 

:~cc • : z • : '-cc ' . . ~ z •:. 1 -c v.. trt- :^--r„zz ere -il -H; t-: . r y 

7C C £Tl „ f " . IT:. _• r ~ £ t e ~ 1/ tCt j - : -1 L 2 _ 3 £ - 3. /. - - i.'.. ~ e .TC Z , C ZZ L ZZ _ „ c C 1 : iC - _ 

: d ic . -r r- ~ — r - c 1 . ~re ^~.pi"cr ~ S:' c~zi tzzz z ; ~ "1 Ice I e r=rr*_7 

f : : car: ic .lar r; ic c 1? /"Trv rl : Ir.c ; : - :v't rdis "rr ~: "rr r : : ': i :^ :.. ; 

COMPILE Myprog 1-7: If 

w;ac;„o S^clr _ 3 ^"iscr/; - z, f^n ciric t 3>:&rer Ixcd nurr r~ - where dee ic -rr 
ir z : •' id zz 1 h = :~: rigi^c .rf: st± - : 3icc:i; IC d~xad - _ - 1 • r_ errccp _e = 

dOr-5 _Ld ridrig B=C112 

Bed' • zz*:e-~z"z • ct ' : : . :: ? ;c: :r la z. .. : -. ; cc t z dc -. \ ^ .. rtec c;r - 

per t io :lrr l^d"*e 1 n *t zzz z f ... 1 : re cf :c r~r-: ry ■ z,z ic ' 1:; 7 s : 

3 "fir?- rigi;* - nunber c: io^^r used icr -y t u.?c 1 ,c«ir:€; recle 

C (sacorid diglr^ ~ ^zmbec zz 1 -rihs '-?e^ r rbj^c- ■ c fe^ 

L ^ third digic" - n;?cer cf 16" is rssd fcr literals Isirirgs, 

J (fr^rlr cigl-" ^ ramber r i : ; i:r? - ? ? ^ f?r rc:----p rs^erarcac 

Tf:-a^efcr£ "zlzc --iszzzlc clc 's i sed 12/16 ($1-11 c.£ :ii^c 1 ' g 1 ^'"allable ™e^er u for 
the sym'-^l ?S 1 e - 1'I^th fcr : cl;s cbjsct c c d ~ brflc^ : /l^Lh lr . ^'r^Irge^ % r 1 
2/ 1 6ths zc r forward rei6rarees xne de f aul : fcr Ctie 3 cp-icr is B=Al3r lie 
value rl : - s^a^^ { 1 - ' " c^cul: - l~ _ r;;c .. c „^r^ rc 

For the dvjr^XCCFiS c~ : - ; r cr should ne^er £:te.cr: cc re 3 ths 1 ^:::cr. to 
prodrca £ l°slir§ Elir cr als^c ec :rr s^ea 'cine 9« r5irg ^he "1 z : : :. z zz dr: s ~s 
because tha lidl di^r Irivs ; 1 ~:1^~ - 1 t- z>~ zz 1% ope ; fcr writing et 

a time rhile a Iris i? crsr fcr reading * £rd tre B ?rcd 1 cpticr.s asch require 
one output flle c Id \ or c rant lo get a _iscir.ge rse L s ? or make a second 
compile c i cr- with 0=N co suppress ere ^1 je^ 



file 



DIALOGUE OF flS COMPILATION PROCESS 

When the COMPILER stEr.St it will run continuously until your program is 
compiled or until an error is de :ec ted , without further ^ c t icn on your par t 
After it "signs on H , it ^il 1 immediately read in your your source program, and 
shcxv a rsridly changing messages 

RE^dl^G LI^S nnn 

where nnn is the line number the compiler is reading. This number will change 
rapidly (several lines per second } ? especially if you are compiling from 
the Workspace. When the compiler encounters an INCLUDE LIBRAR.Y statement in 
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i V: n I >: t - i 1 5 ;„il::.^-:c^. 

indicating :ri£~ it hsi f rl- the ... TD~ f"l = .:, . . 1? . e?i: lag reading the 
jriginsl file ( r.hs ; G§ 3 indic-tes cne 31 = ^ di ive nrrsr^Ci. rc^ Commodore 64 
'"srs'Lcns- ^ f : : ^cl* II . \ : - -• 1 1 ! : -~ . ~;-'.c " ed ~~ith the prth 'c»;e) c Also, each 
;: i: ; :,e the COMPILER reads a ner~ rrccer ;rs rr ftrrrticn r er iri t i.;n in your program , 
; : :' - ; ^ ; 1 ~ y c 1 :.". c ss£?r - rowir r " .1 e c "~ " -~ r re subroutine, 

rr_ crrcr is de tec tec' rr, yoc • r» :~jr^r COMPILER w: "« 1 hslt and di 2 *! . a* 

rhe r~ Feeding line, followed by an error message, for example; 

x3Ar.i:«:G «<I^£ 303 

COMPT Ld f MG func byte re ad joystick 

READING LI^B 309 

IF FIREBUTTON 01 UP 01 DOWN 

* * * -k * i€ * i€ ~k * * i€ * * * * * # * * * 

ERROR 27s 
UNDEFINED 

Want to EDIT W ( Y/ N) ? 

This iacicac3& that the %ari£hle riREBUTTGF has net been defined (declared). 
The — ; c: £^«rlc-;s rid l^:c9 v _ ruch ;f the lire the COMPILER had read 
before rj h t ere r -* ^<-:. e j ** *~ e c *:: e ^ , 

fir line ' ! Wrn - ts SCil 7 ; U - ' asks if you want to edit "re rile •: contain- 
ing :he e . ~ _ r fir :hir rrrr^ -rs '-crkspsco . " 7 ) .. If ;ou rep: y 'rth Y '"' £.r:.f 
<RSTliFJ£>0 ~ tie EDITOI vi? 1 start and ay tcmat ical 1 j position the cursor to the 

cf fending line, simplifying the correction process « Otherwise, you ill be 
retrrred 13 che EXEChT'S, 

t-her Ire king at a compiler error message . note that the ror of asterisks 
may net d.sys indicate the exact location of rhe prctlanc The asterisks only 
indicate how far the compiler had read be f era it recognized ara error « The 
error cot Id have been caused by anything up to this peine in the program. For 
example, s, misspelled variable declaration near tne beginning of the program 
will not cause an error until referenced with rhe 'correct" spelling later in 
the prog mil 5 ^pp^ndi^ contains a listing cf al Ccirciler error messages with 
an explanEticr sac corrective action for e?»cn The ccmr iler error messages are 
contained in file GOMPERRMSG. T. If this file is not present on your disk, yon 
will only get an error number, without the texr of rhe message. 

Assuming your program compiled to completion without an error, yon will see 
a sigaof f message with a summary . This indicates that your program compiled 



Copyright (C) 1986 SMiL Inc. 



Rev. C 




7/^ - 5 1 - ; :;r ' 1 ^. . :1 - n=r el COMPILE. The Demo 

r: I'-/; : ? fcori or rhe dsnc if sn roe fell cnr«pi,- =rc on the PROMAL system 

V - Y~ "i l>v~ i refer :oc lorx -icrrrilai fcr sxall ^:;g £ ^ development • 



Ire 1 emo r-copi^er ^;-es not j:t' the 1 ;iiici x : enrobed above ^ dcec 
it support Ir-t?C?.Ts < EXPORTS , or zzz.zzz'iz zzzz ilzliz z {'zz zzVzzt in Chapter ; i f 
the PROMAL LANGUAGE MANUAL), £::c i c imi^eo co a maximum o c 400 soccer lines 
(excluding ^ccrccr"-:? but including the LIBRARY) • 

Fci era i^l- II; 1 - you use the EXECUTIVE command GET COMPILE, the standard 

comp i i'. -rill cot £• - : zz iz zhz memory MAP and cannot be executed from memory, 
became z zhzzz Is zzc enough ;cc^ in meior / /: zz the compiler and the EXECUTIVE 
at tzz i-^z : z Ti » , II:. * «•* ^ ? zz ~z conseqae: e except cleat you need to keep a 

copy cf toe renpi Lor z z aacr zZ your disks you use for program developments 

PROMAL CROSS REFERS^ nill KrILITY 

XREF generates £ zz t lphfc.be tised lis - ^ f all «-he le entlf t.e ~3 / r_a r.es) used in a 

program v' tl a si "tec" lire c f lire r.v^':e:3 :r which -re-' fjrss, His lice I z 
'■-z :; : :8~f:'l ice lci.~ 1 log '-nere ---a^icr c es ; pro:a ic^ec ~ ?r functions are used In 
- :::grait The XREF utility is nornc 11}- usee after a compilation **ith a 
lie ling generated = Ir this .ie; ? XIEF oil-, epperc the cross -re ference map :c 

•na end cf the liecirg fila- lee syntax of XREF is : 



X1EF [Sourc6i; 5j ! 

wher e 5cc_cetile is toe name of the IIlLol ^lorrcfiLe zz zz re c i , It o>y be 
good i;ea zz llllvij coy other progra^c refcre ; onnLag XlIEII cc ic v-LH have 
plenty wf room for zhe tables it uses internal iy - The opt iooal second argument 
V specifies a version for conditional coup Llat ico , If you are using 
condi - l^tlS 1 cc^px i a*. ion 5 you she old specif; the sane V option that you use on 
the corresponding COiillLE. Omitting rhe v ^iil cross reference all conditional 
blocks . 



When I. IE! is r on , i t appends the cross -re ference map to the end of rhe 
listing file- if one exists- Otherwise, it generates a listing nith line 
numbers \ hot ooes no t generate anr cede or do a ay syntax checking like the 
com pi ler x arc a z r z s s reference oiar in a file ni th the same name as the source 
file bar -~ith a =1 £x:ensicr. c Ihis is tsefui. If yon wish to obtain a cross 
reference cap fcr a progiao. AziJz uill not successfully compile yet 
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You ghoul! £ ;r.dy the manual carefully, because PROMAL is significantly 
different from BASIC . As a BASIC programmer, iuay find some aspecrs of 

PROMAL a little strange at first reading. But if you give it a fair trial, 
we're sure you will soon want to do all if your programming i„ PRCrLal o 

We assume thar you have already read the companion manual MEET PROMAL ! , 
which provides a "hands-on" introduce ion to the PROMAL system as a whole. You 
will fino the operations, aspect of the PROMAL EXECUTIVE, EDITOR, COMPILER, 
and LIBRARY describee ia recall in the PROMAL USE11 1 KANUAL • This manual 
explains the heart or tre PROMAL system, the PROMAL programming language, which 
you can use tc ireat- yor :wn programs . PROMAL is especially well suited fcr s 

* Text processing applications 

* Scientific and Engineering applications 

* Educational applications 

* Interactive programming 

* Small business programming 

* Compilers , assemblers , editors or system software 

Not only ±z "EOMAL ; rc grams fir theso applications often run 21 ICO times 
(or more) faster than BASIC, they are actually easier to program than BASIC! 
Programs that as ad to take weeks 01 ii.ii-i.hs of assembly-language drudgery can 
now be c aicki> developed with PROMaL instead . 

why usl mcm£z,i 

Why should you learn PROMAL when you already know BASIC? Why should you 
learn PROMAL instead of one of the older 5 structured languages such as PASCAL 
or C? 

Perhaps the most important reason is that PROMAL is in many respects 
the most structured language available, because the PROMAL compiler reads 
indentation as part of the syntax of the language. As you will see. tae fact 
that indentation always shows the true structure of your program will make your 
programs easier to write , and more importantly, easier to maintain. 

Another important consideration is that PROMAL is the omlj compiled language 
available from a single vendor for the IBM PC, Apple II, and Commodore 64 - the 
three biggest -selling machines in history . If you plan to develop commercial 
software, or just think you might change computers some day, this will be 
important to you. And PROMAL gives you top performance on all machines . 
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dures , each :: which has a name suggestive ., id Tuiction. 

For example, consider the actual PROMAL program in the right column, below, 
and observe the similarities with the recipe at the left. 



A Kitchen Recipe 
FRIED CHICKEN; 



< — Your recipe name — > 



Chicken pes. < — Main ingredients — > 
Zo shortening and amounts needed 



A PROMAL Program 

PROGRAM LONGESTLINE 
INCLUDE LIBRARY 

BYTE LINE [Slj : carren t line 
BYTE LONGEST ; longest length 
WORD IFILE ; input file 



SEASONED FLOUR : < — Sub Procedure Name — : 

<- 



1 • 2 cup flour 
I tsp c salt 
1/^ tsp . paprika 

Mix all ingredients 
seasoned "lou- - 



Heat ovs.„ tc 450. <~~ 

Melt shortening. 

Coat chicken with 
seasoned flour. 

Cook about 45 min. < — 
until golden brown. 



Ingredients for 
sub-procedure 



:s -:::i:ctions for 
6 /t procedure 



Main Process 
setup 



> PROC SIZELINE 

> BYTE LENGTH ;cur line length 



BEGIN ; Procedure 
— > LENGTH=LENSTR(LINE ) 
IF LENGTH > LONGEST 

LONGEST = LENGTH 
END 

— > BEGIN ; Main Program 

IFILE=OPEN( "TESTFILE • T" ) 

LONGEST* 



Loop waiting for — > WHILE GETLF( IFILE , LINE) 

a condition SIZELINE ; test if biggest 



Serve with gravy. < — How to serve up — > OUTPUT "Longest = #1" s LONGEST 

the results END 

The program above reads a file and prints the length of the longest line in 
the file. It is useful to get the feel for what a complete (although very- 
simple) PROMAL program looks like before delving into the details. 
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L = .. . ... ^ _ r,- .■ 7L~ iaie LONGESTLINE ii :ae command you will 

L~ 712 l';.I v Z when you : : ^.c .:: i :;xs ogram. 

INCLUDE LIBRARY 

This line tells the ??OMAL COMPILE-, tc include the definitions of all the 
built-in library routines (which are needed for input-output; etc*)- You will 
normally have this a tax amen t near the start i 3 ery program. 

BYTE LINE [8i: ; current II:: e 

This line declares -:-at you will be using a variable called LINE which is 
an a^ray cf 81 BYTEs * One byte can store one character, so this array can hold 

an 80 character line plus a line terminator* The " ; " indicates the start cf a 
comment . The rest of a line after a " ; " Is Ignored by the compiler. 

BYTE LONGEST ; longest length 

This line declares a simple (non-array) variable called LONGEST, it is 
used to "^old the number of characters in the longest line. In PROMAL : unlike 
BASIC ? all variables gggt be declared before they are used (not just arrays). 

~*0PD IFILE ; Input file 

This line declares a varlf ~ ^1 t ;' ce WC3.2 * la,: 3*.; you will laarn t'-<a " a 

WORD Is usually used tc ho" c -r» adcr es? - In this case, the address will cs s 
"file lisaile" for the file of text tc be read. You can think of a file handle 
as jusc £ number identifying £ particular f lie- 

?R0C SIZELINE 

This line begins the definition of a PROMAL procedure, ivhich Is similar to 
a BASIC subroutine <» It has been given the name SIZELINE by the programmer. 

BYTE LENGTH ;cur line length 

This is a variable of type BYTE which is only used within the procedure. 
This ^11 1 be explained further later on. 

BEGIN 

This line signals the beginning of actual executable Instructions within 
the procedure. 

LENGTH=LENSTR(LINE ) 
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END 

The Er? s ;a :eriexit indicates the er.; ;>£ the procedure (like a BASIC RETURN 
5 t atement * - 

BEGIin 

Since th-~r = : f ~ _c r "f'fl^JRES, the BEGIN signal* -:hr beginnir.5 or ~Ls 
z^ln program ??_OIf-_L : t 7 oe n£l:2. program always comes last. This may seem a 

liccle sccar^e c/: fi~ 5 : , 1 ~ .. . o s from the general rule that Everything, 

Including all suh„ oii:L*ie^ : defined before being used. 

IFILE=OPEN( "TESTFILE . T" ) 

This is actually the first diauenient which would be executed in the 
program Zz :ells the computer "OPEN" the file called "TESTFILE. T" for 
reading, acd installs the file handle into IFILE. Any subsequent input 
references to IFILE will read from "TESTFILE. T" . 

LONGEST=0 

This s :£teOi£T- - ,",.rk.s juat like its BASIC equivalent, and initializes the 

vai-e ~\ 1 IGESi % 

WHILE GETL1 CHILE. VhlE) 

SIZELI. 1 ! ^35- if biggest 

These two statements comprise a loop. The WHILE statement attempts to read 
one line froM the file into the LINE array, if successful, the SIZELINE 
subroutine is celled, and the WHILE statement Is repeated again. This process 
Is repeated until end-of -f He Is reached, In which ease the GETLF function Is 
unsuccessful, and control passes through -::l*:hcat executing SIZELINE again. in 
PROMAL 5 eubrc-tis^B aire o&ilsd b~ izsrslj .~r:>— -I their roesss? r.c GOSUB Is 
needed 

OUTPUT "Longest - #Z" . LONGEST 

This statement Is similar tc a BASH ??INT statement. It - ould show an 

answer on the screen, for instance; 

Longest = 67 
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VOCABULARY 

The following reserved words have special meaning in PROMAL programs, and 
form the basic vocabulary of the languages 



AID 


CON 


EXT 


INT 


OWN 


TO 


ARG 


CHOOSE 


FALSE 


LIST 


PIOC 


TRUE 


ASM 


DATA 


FOR 


NEXT 


PROGRAM 


UNTIL 


AT 


END 


FUNG 


NOT 


REAL 


WHILE 


BYTE 


ELSE 


IF 


NOTHING 


REFUGE 


WORD 


BEGIN 


ESCAPE 


IMPORT 


OR 


REPEAT 


XOR 


BREAK 


EXPORT 


INCLUDE 


OVERLAY 


RETURN 





The reserved words may be spelled with either upper or lower cass Is t ~srs , or a 
mis cf both. Therefore BEGIN, begin, Begin, and Legl~ are equivalent :h~&e 
reserved words are also sometimes called keywords < In PROKAL "r,rllke 3I.SLC; 

you must separate keywords from each other ;r z^z'z, zczer names i~±tfi blares ,■ r 

other punctuation. This helps make programs readable and does not impose any 
speed or memory size penalty on the program. As a practical matter you may 
also wish to consider the standard library routine nanes listed at the start of 
the LIBRARY MANUAL as reserved words, although this Is not strictly true 
because you do not "nave to use the LIBRARY. You may even change the names in 
the LIBRARY, although this is definitely aoi _ecommend 6c . iCk reasons or 
consistency with other programmers). 

mffiS 

Names are used to Identify constants, variables- sata, functions, proce- 
dures and programs it* PROMALo You may choose names (also called Identifiers) 
as you ^ish - following these rules : 

1. A name may be from one to 31 characters in length, 

2. The first character must be alphabetic. 

3. The remaining characters must be alphabetic, numeric, or the underline 
character " " (left-pointing arrow on the Commodore 64, which has no 
underline key) . 

4 . Either upper or lower case alphabetic characters may be used. Both are 
considered equivalent . The PROMAL compiler treats all alphabetic 
characters as upper case in Identifiers. Therefore XYZ and xYz are 
considered the same name* 

5. A name may not duplicate one of tna reserved words in the basic vocab- 
ulary above. 

Unlike Commodore or Apple BASIC, which only looks at the first two 
characters cf a name s all characters of a name are "significant" in PROMAL. 
For example, EXTRAP0LATEX1 and EXTRAP0LATEY1 will be considered as two 
different variables, even though the first eleven characters are identical. 
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A ZERO 

ale for4 D200 

C4 d2000 ET 

Some eiEz: 1 !? of ILLEG-/1 rme? ^1:^ reasons indicated) ares 

B-4 : scond character is nc: a-.pnanumeric or ) 

3D ilr ~t character is no; £lph£betic) 

LIST plicates ^a^—a- 

Ag> ; snember tk? t canr : rnn variable names and PROMAL keywords 

together the ^ay you car: in BASIC . For example, 

IF::-^3CRiD=Y0U 



may be an acceptable way to start an .-it statement in sitSIC, but it PROMAL you 
would have to write; 

IF ID=ME OR ID=YOU 

instead. 

A :s. ~y?a refers jo the liisd or data that a program can manipulate. 

??T' 7 LeC iE3 it.-; :; built-in d?ta nypss r three ci which are very simple and quite 
close tc the data types tnat ara used in machine language. This primitive 
simplicity greatly contributes to PROMAL " s speed of execution. The four types 
are; 

Type Meaning 

BYTE An unsigned integer number between anf 255 - or 

a single ASCII character, or 
the Boolean value TRUE or FALSE. 

MOID An unsigned integer number between and 65 < 535* 

ISa A signed Integer number between -32 ; 75" and -*-32 s 767o 

EE£L A floating point number between approximately loZ-37 and 

l.E+37. Similar to BASIC"© standard numeric data type. 
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rciraric caca dyes uas^ ±n drill " cjzaa each . r \: era £cc;r^ :t 11 rirrfii- 
caac digits instead cf ■;, srgcif lt£^ dig„r like darld= dial, "/erii^lar "vara 
rda arsaia.ic flexibility because rdray car, score vary large end very r^add 
numbers, including a decimal fra_:ion. Zo r ' 7 e"ar , they are manipulated much more 
slowly than -"-a other data r; r re& " : ut : a- slowly as in d,dd"-^ .. and therefore 
should be ased with discretion^ ??..0MA1 ads: provides facilities i::: "c rmatted 
output, so that "ru car. r^ecissd" ~ : r : • _ ' ":a-. number _. r digits and number a d 
decimal places printed err REAL output. 

laSdd iz og rammers ma; acre L jz :. 1 j-.a-a r~ e ~ ^Ligt a=> c % ~ - a : 

data :vpe. But PROMAL eav saddle strarga --27 ere^l as aa srrsj rf drvs dear , 
iz:l\g handling is not dl llraalr i l„5 %ill 3c di^_ ric,2 ^a cattle - ^ i. - 

vliEEJtL NUMBERS, CHARACTERS, AND STRINGS 

Numbers may be written in the usual way. A number v«riceen without a 

decimal point is assumed to be cf type BYTE , INT, or WORD, depending on its 
size and sign* Unsigned values less than 256 are assume 1" I: be BYTE. Larger 
values are type WORD. Any negative number is assumed tc da 111. 

Examples of legal BYTE tmt or WORD type numbers are; 

1 Id? 22340 65535 -78 

The fcldcacirg are iilsgsl as BYTE, INT or WORD type numbers Ifcr ^ae reasons 
ir di c^ced** % 

1 , 33d 5 ( Cannot have a comma) 

120c £ [ 1 anno t have a decimal pod ;.t - ^11 far ~ d; -dd. reader- - 

6553S ; ; Cut of range - cast be less ra^a. 5553c; 

Literal numbers may alec re specified ir l?ar.edecii 



prefix. Hexadecimal (base 16) aaEcars are eftaa acre eoacarrdeac £cr specifying 
memory addresses or bit patterns. 7rr exaap 1 e : li is easier tc rariarrbar tt.rt 
the Commodore 84 VIC-2 video chic is ac address |DCdC raaa a: :ia eecicad 
equivalent , 53248. If you are ao ; familiar v-. i th hexadecimal arrears ; yea raa; 
wish to consult your computer's reference reread ~ Fxanslas cf lagsrl ran 
numbers are : 

$0 $a $2BD $FFFF $0012 
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zz stecily .:. ££^1^^ point for a real nonscanr » lou xay a~so vrire REAL 
literal numbers using tre *"r te ;:: r scientific notation, as in BASIC. 
Example - •: f legal REA1 : c'z^z., ? r:s? 

0. ,C 123c 3* 1*1 5*?*5?5 -.0000007 56.00 
i.lsii --003E-I0 

Th - 1 : ll-r~: c z re illegal real numbers 'zziz :;s reasons indicated) : 

ISCC-l ; 'nc decimal point - rill be treated as on t-of -range integer) 
l ; 333.Gvi z 'cannot have a cornea'; 

1 , 1^.E— 50 ; (value out of range? nnst be less than IE >-t *^ \ 



In specifying literal numbers , you should keep in mind cha size Halts for 
the various data types. Only REAL numbers may be larger than 65535 decimal 
($FFFF) and may have a fractional part. 

PROMaI programs cf ten need to specify single ASCII characters for some 
operation (AppeMis Ik contains a summary cf tie ASCII character set). To 

specify a single literal character . enclose it in single quotes, for example; 



'4' 



The PROHaL compile"' ~~±1Z -rbstitc^e "la numeric ASCII value c: :he character. 
For example, writ: r«n 'A" is equivc ent t ~ ^ ^r S&l ' eee table . Appendix 1.) *. If 
you need to shove the single quote character Itself " ; as a lireral character, 

you must doable I" ~~ " \ - 



A liters! 3 "ring is a group of characters enclosed in double quotes « 

Examples literal strings are; 

"A" "Hello There!" "26" "+-*/" 



When the compiler encounters a literal string in your source program ; it 
generates the ASCII representation of the scring, followed by a $00 byte 
terminator in your object program* lirsrsi strings -iss one byte per charac- 
ter s pks & string terminator wMen is sl^rsje r. ?CG fcjre. Therefore the string 

S, A" occupies £wc bytes of memory and tr,e string r 'Rel! :. There I" occupies 13 

bytes in your compiled program^ Tne last example ; f *^ above is called the null 
string, and contains no characters. This is not the same as a string contain- 
ing a blank. A blank is a character and occupies space in memory. The 0-byte 
terminator is always generated automatically by the compiler . A literal string 
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PUT "Hello world i" 



PUT is actually a built in procedt 

a string which is to be printed • 



PUT 



lr actuelly icr:S":; zaz e firing for yc . In memory (tariinate: 27 - C ly: - . ; arf 
7sr:e^?ter 5 r-_l t ~ -'hr tit procedure, casing PUT the addr - - f /-e --ufa^ :„ 
print e The c^ipiZe^ r-es the address of the first character cf the string ce 
*^5ls Talue*" tf tks scrlmg. If you don't under 5 cane this ;od;:jc-';'" t 1- • h 

-jorry about :to The importance and usefulness of this will ce explainec mora 
full; later. 

If you need to include the i: able-quote character itself ; in a literal 

strings ir siould be doubled = Fcrr examples 

PuT " She said, ""I'll be back. 98 9 *" 
vrill actually cause the program to prints 
She sa:hc "I h'._ he hack. ,r 

Yon can also embed unprintable cedes " % s^zh as ASCII control characters or 
special characters , such as charactei s cz> trigger color changes 011 the Commo- 
dore 64) in a string by writing the ehara ~ :-t \ [ h pounds sterling key 011 the 

Commodore 64, which has no backslash r.37 * fallowed by exactly h^c nes: eiglus 
giving the desired character code. F; r euarxle: 

PUT "lew line \CDstarting here" 

will embed a $0D (ASCII carriage return) in mid-string. If you wish to include 

the \ itself in a string, you should double it ; in the same manner as the 
quote* A particularly useful pair of embedded codas cu zae C-64 are \ 1 2 and 
\92, which start and stop reverse video output, respectively. On the Apple II ? 
\0F and \0E will enable and disable reverse video. 

it is important to remember the difference between a character and a 
string* A literal character is always a single character enclosed in single 
quotes. A literal string is zero or more characters enclosed in double quotes • 

This means thar "a" and 'ha" do net have the same meaning to the PROMAL compil- 
er o " k' occupies a single byte and has the value 65. "A" occupies two bytes, 
65 followed by C > and has the 58 value" of whatever address the PROMAL compiler 
assigns to the first character « 
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T£.riS~lc:e vXt-n U-Lt-g fhhtAh, .X^ivil » yJU IUS^ £s?;5: - T.S type, and na^e C~ 

every variable explicitly instead. No special suf f l re used. 

DECL&L£*3£ t:ih^hhs 

^n t l^v-.^ u^gJcjiS; o-s-i -arid:, EESirft co cellared before they are used. A 
varin : Is ieclsr?ticn tslls cne PRhCiL icapilat cha name cf the variable, what 
type cf 7o.ri.c-. i; i- r ai„h now i^c-.. £ : «cCfe I"; veil need . A sample variable 

decla— iii ~L*h~ 

INT SCORE ; Game score 

-hio declc . es tr- c " : u will be usinp 5 -vallate - T itb che name 3fthZ : nnh that 

Ic 3ill be -~f :>po -hT. There.: e er,e ^sciace iGObt Till be able tc take on 
signed valiss between -3276"' and v%:2"*" c ~ 7 , Chhly on© triable msy fee eacl&red on 

£ lls^c 1c ic considered good ^lo* racing pra^;iea tc put a comment after the 
variable name explaining wha :, is j^ee fcr £ as is shewn above. 

in B-^lf. yen il^ not hi"va tc feeler'- '-^riab'e^ Jezcca:; fot :'r? flic state- 
ment- vhi ch if c -, declaration for arrays) Having tc list all veer variables a: 
the ccp chc ^, s .;a.i cay seeu liice a nnisanca at i:._-C boc ycc will come cc 
appreciate the ~~alca jf it= When per pic v up a PRC teal, prcgras:. ~ T cri can quick'' ~ 
±lrd a. -h^ r,c %f 1 the variables in :he pcograx ai 6 ^hac zz~j sr^ used 
icj £}' raa-i^g :r a reparations - If '-art •;: adc a ns"" vsricbls ye; won't 

have tc search the whole program to make sure the name you chooss hac ret 
al.. cicy hasp use:, rev something else; you ju^c tc - . at : ae declarations* If 
yen r c g = c ._c declare a variable before you use 1 1 . .i h~ PROMAL compiler will 
f leg ohe variable name with an error message saying "'UNDEFINED " when you try to 
use it, 

bhare i? ar. seen more important reason why variables need to be declared. 
This is best i 11ns "crated with an example from BASIC. Suppose you decide to 
modify an axis ting 5 tSIC program which uses a variable called XO. You add a 
f e lines to the program, using the variable XO, but the program mysteriously 
dcesrh z i crk. Eventually you discover that the reason is that you typed XO 
(X- "laccer C * c ; bar the original variable was XG ;z- ; hero :? h In tins case, 
BjtSIC acto"£ tiaallv creates a aev vnr labia ? initialized z i : z a ^al^e of zero, 
ins teat cf j.5ing existing variable XC vrhioh jcu reallp \vanLcd = In ?RGkAL ? 

you ncul n noc have this problem because che compiler ^culd flag XO as UNDE- 
FINZPc A3 a xatter cf hiatcrical interest; ona of the I\^£t. space program's 
planetary probes was lost due to a navigational error caused by precisely rhis 
kind cf bug in a FORTRAN program (like BASIC, you don't have to declare 
variables in FORTRAN). 
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single statement. 



A constant is a :.a.ts giver, zc a njineric value which -.ill not change 
Lhroughouc t v ~. _-r~gr~:z- y -:c-~? , '"t .-- e defined Tizb £ CjF s :^ tement before 

it can be used <■ J:-r ezscDie? 

CON LF-10 * ASCII linefeed character 

v£ r t ibs the ^ynccl IF to be 13. ri:ar ;.:is^ anytime the PROMAL compiler 
encounters the nasie LF , it vslll Substitute the valae 10 instead* There are two 

differences between constants ana variables o First, the value of the constant 
is permanent and is associated with the constant name at compile time. Second, 
no memory is set aside to save the value of the constant in the data area. 
Instead, any tine the constant is referenced, the compiler generates the valae 
of the constant (in the same manner as a literal cons cant) iri the executable 
code of the program. Only one constant can be defined on a line. Again, it is 
considered good practice to add a comment to a constat; definition explaining 
what the constant is o If you are an assembly language programmer, you may 
recognize that a PROMAL constant is equivalent to an assembly language 
"equate" . You may also define the type of the constant explicitly, for 
example; 

CON WORD STABTL0C-$40 

defines STARTLOG tc be of type WORD with a value of 40 hexadecimal. If you 
don't specify the type explicitly* PROMAL will assume type BYTE if cha value is 
less than $100, INT if ic has a minus sign, and type WORD otherwise* Later v 7 e 
will learn more about constant definitions, after we learn about operators 
and expressions. 

You may mot declare a REAL constant. Instead s you should use a DATA 
statement if you wish to associate a name with a permanent value of type REAL. 
Disallowing REAL constants saves memory and reduces the complexity of the 
compiler. 
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BYTE Bitt-l 



declares a:, ar~ay ci cy^e BYTE which can r.: ... ' 1 eleuents {Eu^iR'O^ through 
BUFFER [80] ; 6 1; is important to observe iV:: °. c yv isri^- a.r ar^y as 7[F], 
then tha Isist slassrt 15 Zj^-IT. ret JJir z , baccrsa is :re :irst rlsr-snt. 

It is considered good programming practice to define a constant which 

controls the size of a subsequently declared array. This will usually make it 
easier to alter the program later . For example; 

COM BUFSIZE - I 01 
BYTE BUFFER1 [BUFS1ZE] 
BYTE BUFFER2 [BUFSIZE] 

You may not use a variable as the dimension for an array s however • This is 

because the PROMAL compiler allocates memory for the array at compile time; the 
size of the array must be known at compile time, not when the program is 

actually run. 

The subscripts for ac mrz&j of amy type mzst always be cf type MOID. If an 
array subscript evaluates to type BYTE ? it will be "promoted" to WORD automa- 
tically. L subscript which evaluates tc type REAL Till carsa tie conrilar :,: 
generate ar_ error message, The maximum subscript xhich can ha ased is 
dependent cr_ the amount cf free memory* When you refer te errsy naxs 
without subscripts (or seekers) s the address of the errcy -gill bs trsaeL Ire 
importance of this - 7 ill be illustrated later. 

It is possible to define both simple variables and arrays at specified 
locations in memory c For example you can define the screen memory as an array 
starting at $0^00 (1024) „ This is kind of declaration is called an external 
variable, described ir Chapter 6 9 "Interfacing". 

CAUTIONs when array elements are referenced, PROMAL does mot perform amy 
bounds checking (because of the adverse affect on performance) . Therefore a 
sequence likes 

WORD i 

BYTE BUF-IG] 

BYTE LINE [8] 

1=12 

BUF[I]=0 
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results will occur! 



Multiple dimension arrays have the subscripts separated by commas, for 

example; 

BYTE St !EIi;iLr^Z J' ..Jj 

ri>ll ft-:::.- — 

IF SCR££r:lrl^SZ °I I' - ' 

SCREENIKAGE [ C ; I T - SC^EEHii^E f 1 : 1 ? 

BEND = TORQUE * STIFFNESS 1 1 ; : 5 It] 



The amount of memory required to store an array is the produc c: :..~s 
declared dimensions times the size of each element. The SCREENIM&GE array 
above uses 2000 bytes, and the STIFFNESS array uses 3,6:C byteso hnlt^rie 
dimension arrays are mapped into memory such that incrementing zhe first 
subscript will address elements that are physically adjacent in aexcryr Cr , 
another way to visualize this is co say that SCREENIMAGE is organized as 25 
groups of 8G bytes each ; sot 80 groups of 25 bytes each; < Therefore if yen 
wish to have a two dimensional array of text s che column subscript sfciouid come 
first and the row subscript secoro : as was done for SCREENIMAGE above. This is 
discussed further in Chapter 1 , 

&, cata definition is similar tc a variable but has a predefined initial 
value which is determined at compile time. For example; 

DATA REAL ?I - 1-15526535 

defines a data ite 1 ^ of type REAL vrhieh will be predefined to the value of PI. 

Unlike constants 9 data definitions can define arrays as well as simple 
variables • The DATA definition is most frequently used to define a table of 
values which will nor be changed by the program* The DATA definition looks 
similar to a variable declaration, except that it starts with the word DATA and 
is followed by an and the desired value (or values), for example; 

DATA BYTE MYTABLE [] - 23, 12, 8 5 4 ? 2 r l r 

This line defines an array called MYTABLE of type BYTE having 7 elements. 
Notice that the size of the array is not given in the brackets; the PROMAL 
compiler counts the number of elements for you. Yon must explicitly define the 
value of ail elements. The first element of the array will be MYTABLE [ ] and 

will be initialized to 23. The last element will be MYTABLE [6] and have the 
value 0, 

You may mot define multiple-dimension DATA arrays. Only a single dimension 
is permitted for DATA declarations. 
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If you wish to use ^_L^ of da- : ;.. : to set the initial values ci s 
variable array which £ ;:sequen-_r- le -itered, the correct procedure is to 

copy the data array to another vari- 11a = rray (using the BLKMOV procedure, 
described later), and then alter the variable array* 

The data definition is the one statement in PROMAL which can cons.5. zZ 

multiple lines. In o->~~i conrinus the data definition on additional Lln-r. 

either the = sign or a zo^fls, should be the last character cf the preceding 

line. For example; 

DATA WORD LIST ~ 1 - 
3,45,13.27, 

1-4/, 14,29 

defines an array cf 16 words - 

DATA sta cedents are frequently used to define an array of strings which can 
be used for messages , etc. during the program. For examples 

DATA V?ORD ERRORMSG I ; - 
"Function Successful. " , 

Ii:i es ^ ; -' : f te >. 

Elegit not rc_nd • , 

"You mu?c specify a Widgit lumber 

Thrs- 9te/:emenz cef in~s a table of four words, es.cn initialized to p :in" zz z, 
string. Later in your program, if you wanted to print the "Widgit not found." 
error message, you could simply write; 

PUT ERRORMSG [2] 

PUT is a built-in LIBRARY procedure which displays the string specified, in 
this case the third string in the table. 

Please note that che type of the above data array is WORD, not BYTE. This 
is because each element of che array is a string* Yen may recall from our 
discussion of strings that the "value" of a string is the address of its firsc 
character; therefore a WORD is necessary to hold uhis address. 
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Result 










— 


lclli£~ v < - negation 








r>;. ".ui: " ~ ".: 1 z , 




-1-188 




.;; :ia:;ion discarded exc • "„ 1 • ' } 


j: . 11 


6 




Fex-inde ^s,-zi. 


200 % 30 


20 




Lsf: shifc 


"7 s s i 


* L 


» 


Right shift 




iGA 


K 


Relatione 2 z per e z\ r 1~ ^ s -:l^.r. 


s •;. 


TRUE 


\- 


Relational operator lass tnar. zz equal 




TRUE 


<> 






FALSE 


a 


Ralat Icna 1 operator ecral 




TRUE 




Relational op-rrs*:^ crrsatsr — -^n or eqr< 


10 c ^= 


FALSE 


> 


Relational operator greater than 


3 > 8 


FALSE 


AND 


Logical AMD operator 


3M .-171 4<10 


TRUE 


OR 


Logical OR operator 


K-l 01 8>9 


FALSE 


XOR 


Logical exclusive 01 


$00 XOR $FF 


$FF 


NOT 


Logical complement 


NOT TRUE 


FALSE 


# 


Address of variable 


#X 


aadr cf 1 


K 


Extract low byte of WORD or INT 


$1234s< 


$34 


s> 


Extract high byte of WORD or INT 


$I234s> 


$12 


s -f 


Convert to WORD 


$5A:-f- 


$005A 




Convert to INT 


$FF : - 


+255 




Convert to REAL 


45s o 


-5.1 


i< 


Indirect through pointer to BYTE 


?TR@< 


see text 


@_ 


Indirect through pointer to INT 


PTR @- 


see text 


@+ 


indirect through pointer to WORD 


(PTR"r2)^ 


see text 


@. 


Indirect through pointer to REAL 


PTE §. 


see text 



Sox s cf these operators may ioc\ 7 a ni liar from your experience with BASIC; 
others ere entirely new. These oper^^o^s may be combined with operands, which 
may be numbers, characters 5 strings, constants, variables, data, or functions, 
to produce expressions. We shall now examine the most important of these 
operators in detail - 

ARITHMETIC EEFEESSI5KS 

Like BASIC, arithmetic expressions are evaluated from left to righc *In "he 

absence c parentheses), with multiplication and division having a higher 
priori than addition and subtraction. Therefore the expressions 

' 4*5 

evaluates as 23, not 35. A summary of operator precedence is given below. 
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( operators in the o zr ;„ .~~ ~* ~. o>:_ : : ~ . _ -vr-l ? - 

. , - t K, @+, :,; Highest precedence 



\~ 11 h Lov^s. ^ 

""he a*;~';: v _etic operato' :~ . — ~- ~ e ~.nd / , wcih io lis sxoso :s-i fashion, 
>^-- v'ith e lev twists. Fir?*; 00 a _ 1 - remember that PRCxiAL deals integers 
'-;->. e. nurh-r^) as well as oa-I -it^csrf ■ The resulo of avl :h^s :lo on type 
BYTE, .JOES :r 112 cannot have a fractional result* Therefore 5 / 2 evaluates 
as 2, " - - ~ - -~y fraction is always discarded;- 1t^o~ c :: , r : evaluates 
as 2 , 5 , hecarse the presence of the decimal poln-t oolls ths ??.CIIAL compiler 
that *: v e numbers are REAL. 



Note oc- losssctore §4;- ha careful tot to type the shifted character 011 
the keyboard whan yon want a plus sign. It looks Ilk*? ? plus sign, hut isn't 
(the same applies to BASIC) - 

Most opera tors take two operands. For mo s o operators, these two operands 
do not have tc be of the same type- In a mixed expression involving operands 
of different types, the operands are usually "promoted" to the "higher" type 
automatically, where BYTE is the "lowest" and REAL is the "highest" typeo The 
table belox% summarizes the results cf a partially evaluated expression of the 
zjpe shown in the left column when an operacc;: is encountered with a new 
operand of the type shown in the top row: 



RESULT TYPE FOE MIXED MODE EXPRESSIONS 



Next operand Irr-ol-ec Is ^ 



Present 

Type is 



\ 



BYTE 



WORD 



- 



HI 



BYTE 


BYTE 


WORD 


INT 


REAL 




WORD 


WORD 


WORD 


INT 


REAL 


<-j 


INT 


INT 


INT 


INT 


REAL 




REAL 


REAL 


REAL 


REAL 


REAL 





P.esuxt type 



The TYPE cf the data being operated on must be considered o For example, 
adding two variables of type BYTE will always result in a value which Is also 
of type BYTE, even if the result Is too large to fit In a BYTE variable* For 
example, If X Is a variable of type BYTE which has been previously assigned the 
value of 254, then the expression X+4 will NOT have a value of 238 s but 2. This 
is because BYTE variables can only take on values between and 255 , so that 
when you add 4 to 254, the result Is (258-256) = 2. 
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Since 1/ : rl 7 • ^ a 3711 — — ^ ^arrctl^ in unsigned, ycc car." : apfly rh~ 
negation operator cr ir 6irecrly ; the ct-x it r ltomaticalT 7 ;::ic;s: ;r tpr~ 
INT (integer', wsfcra t:-~ negation is psrfcmed. "his "promotion J i-i 

in the temporary :jcr7 area called 7ns accu^clajcr "7 ere PROMAL doss 7s 

arith n :- c ": 4 «ot change :ca r ; ""-;e 11 liir ~I 7a original v aria~:7r = 

An o;^rc-*/ rf tpps WORD alsc s7?d 7 s po^ir-, 7 ^ raj in rhio cs.se 1:7s 
largest possible "odometer reading" is 55533 17 IFF nex; . for example if 7 is a 
varia7.a ci rypc 7CE7 with a val-r :f \ "• 7 -~ :> -57^4 ($FFFE) : net -2, 

OrJpr integers and teals may take or nagati 3 "aL:ss< To understand ho" 
integers ~or^~ again consic-ar your auto odometer* If yea started out a: 1 sad 
turned the odcre "er bach 1 Gila it would read 9S7S$5eCe Turn ic bac> another 
mile and it c?ou!d read 3 0* If you T *antsd to use your odometer to 

measure both forward and backward movement from C . yon might define ever} thing 
f rem tc 43.995=9 as positive, and everything from 50,000.0 and above as 
negative ? effectively splitting the total number of reoresentable numbers in 
twc (half positive and half negative) . This is exactly how INT variables work 
in PROMAL * 



In two bytes there are 55^ SIS possible numbers, which we divide in two , 
:-it7 to 32767 ccing considered positive ($0000 to $7FFF) . The other half of 
the numbers represent negative numbers , with -1 represented by $FFFF . The most 
negative number possible is -32768, or $8000. However, since there is no 
+32768 number representable : the number -32768 is disallowed. This number 
scheme is called "two's complement" arithmetic, and is standard on almost all 
computers . 

For example : consider tee f rllrwing fragment of a PROMAL program: 



BYTE X 
WORD Y 
WORD ANSWER 

X « 254 
Y - 300 

ANSWER « 7 - Y 



This will produce the expected result cf ANSWERS 54, However, if you 
change the last line to read z 



ANSWER = X + 3 + Y 
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ther ~\e r-_ : :1\ "rirli '-z~ :f " ^ '.^:auc:- Y Y would be evaluate - „x.£ „^ vith X 
beirr r-^-ter :: 'r = i~~~ making ~ - : iitioit. 

!r:;~ f nL.o time you will not ha -~ . orry about mixi ..._:Ti.- = - r-?ps in 
an exprr^i:-:- but when you do you ^{^ill \ *t r min,- ^_ J ^ valuation. 

You car 'frrr.e" an operand to be prrcr :~c (or "demoted") £r:=n .re "_ype to 

another r "lYr the "type cast" operators, which are : 



:< 


Extract 


low order byte from word or integer {zz convert real to by :.e 


:> 


Extract 


high order byte iron word or integer* 




Convert 


to word (unsign^r 1 - 




Convert 


to integer (signed) 




Convert 


to real 'floating point). 



These operators are written immediately sfrsr the operand which they are to 
change, for examples 

ANSWER - Z%- + 3 -r Y 

would result in Afc SwER=557 i , because the : + operator will promote or ~ e csst" X to 
a word before performing the addition with Y. The expression Xs+ is read as "X 
ease to a word" • 

There ere four special cases for arithmetic operators. 

lo The % operator (remainder) cannot be applied to REAL operands . The sign 

of che result is always considered positive for the % operator. 
2 If yer multiply or divide two operands of type BYTE, both operands will 

za promoted to WORD, and the result will be type WORD. 
2 - Taking the negative of a BYTE or YORD conver ts to an INT. No error 

is given if the result is out of range (result truncated ;e 16 bi£s) e 
4o Dividing by zero will produce s fatal run-time error. A "zero fi^ide" 

error can be triggered by any of the following % 

a. Division by ( X •'" }< 

b. Remainder by ( X % C). 

c • A REAL result larger than the largest representable value (about 
I,E+37). 

dc Conversion of a REAL to a BYTE f WORD, or INT which cannot be 
represented (e.g, 9 IGOOOCo t±) 9 
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a ':~.:::~a.'-:i ~ :n zz -;.\^ a~ .... . ~hc: £ ~ 1 -h---.--.,!^ ^ : ..< ..: . .. n .. . . . . . .. is 

\ -ay? t / r \ y : r 



The fact tin: zze result of a relational operation can be interpreted as 
-; - J zis well as FALSE or TRUE can be, useful. Fc: example, the two statements : 

IF FEASORS > 100 
SCORE = SCORE + 1 

ce "-a replaced by the single equivalent statement; 

SCORE = SC0I3 4- ;PHAS0RS > ICO " 

because the express loa (FEASORS > 1 mil evaluate as 1 If TRUE and S ether- 
wise. 

The relational operators all have equal priority of evaluation and are of 
lower priority than any arithmetic operators, so that "normal*' comparisons will 
produce the expected result when written without parentheses. For example ths 
expressions 

3 * 3 > 3 4* 3 

evaluates as TRUE 

Please n~t^ that you may not compare two string- c ^±zzl : ; using the 
relational operators on the variables involved, becaase this v^mld merely 
compare the addresses of the strings, which has no relation to the content of 

the strings* To compare strings, use the CMPSTR function, described in the 
LIBRARY MANUAL • 

mGlCMJs OPERATORS 

The logical operators (AID, OR, MOT, XOR) may be combined with relational 
operators or used for bit-by-bit Boolean operations c These operators may only 
be used on operands of type BYTE, which is normal if using rhem in conjunction 

with relational operators. All logical operators have an eqaai priority of 
evaluation which is lower than the arithmetic and relational operators, so that 
"normal 95 combinations of operators will produce the expected rest-it without 
parentheses . For example the expressions 

X > 100 AND Y = 

is equivalent to; 

(X > 100) AND (Y - G) 
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PORT AND $QF 



will "mask off" the high order PORT. As you may have already discov- 

ered, these masking operations air frequently need - i t : manipulate selected 
bits within a byte. 

The operator NOT is a unary operator which converts any non-zero byte 
arc T re 1. To perform a bit-by-' - -omplemeitr use XOR $FF instead. 



SHIFT OPE£ArO£S 



The cpei^c- - -* €.;i£ % r perforr _ = _: - right sli/ "t- respectively • The 

operand to h? spicier ^oeenrs on the ?ice ~£ "he oper- t ^r , ? cd the shift 

count on the cl&v^ r *-r sample : 



XVAL '< h 



shifts the value cf Zh^h left Ly fori ::;cc Shifts may be applied to ell ieca 
cy c^a ~>:cept WLrSLi hoover r trie -«sift count nest be of type BYTE* Ths shifc 

cernt should be In the r^nge cf 'j-g for BYTE operands and C— IS fcr WCRI :i HIT 
operands . Shift operators have ths same precedence of evaluation as nclcipli- 
cation and division. One cf the nost frequent uses of shifts is to perform 

multiplications or divisions by powers of 2. For example; 



COUNT <<* I 



will compute eight times the value of COUNT much faster than; 



COUNT * 8 



Rigf z shifting by & is equivalent tc , and much faster than) dividing by 2 to 
the Nth power. Shifts are also sometimes used in conjunction with the logical 
operators for manipulating data into specific bit- of ^ register. Bits shifted 
que of a byte or word are lost; J oits are always snirteo into the vcrr? (even 
if it is a negative integer) o The result of a shift cn rype INI is type WORD* 
There is no built-in operator to perform bio vstez! ons * 



INDIRECT AMD ABBUSS OPERATORS 



The operator f? is the address operator * It can only be applied cc a 
variable or data name (not to a number, string, constant or function} « The # 

operator returns the address of the variable which follows it o Fcr example! 

WORD PTR 
REAL STRENGTH 

PTR = # STRENGTH 
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WORD PTR 

DATA BYTE COMDCHA? : / - "L ' 'L 

PTE = #COMDCHAR[2] 

will set PTR to the addr = ^ of . . . . . r . 

The operators §<, I ' .. ^^ators. They are used 

to access data "pointed :c a ^ ~ y~rji-;%L~ - T expression. The expression to 
the left cf the indirect: operator s'roald be of :vpe WORD. If rt is cf -vpe 
BYTE 9 it will be promote! t/ : se ^O&D - af^icaliy - For example; 

WO 15 l* ?0 1 l{r ' T F R 
REAL VALUE [iO] 

POINTER « #VaLjE: 7 ] 
» • • 

IF POINTERS. > % 



Here POINTS? is set tc "he address cf a certain element of an array cf REALs . 

Later, the expression POINTERS, can he used to test the value of ttst element. 
The expression "POINTERS. " can be thought; cf as "the real number pointed to by 

POINTER. " 

One of the most common uses of the indirect operators is to extra:': charac- 
ters from strings. For example, consider the fallowing program frogmen;; s 

BYTE BUFFER [80] 
WORD PTR 
BYTE CHAR 

PTR= BUFFER 

CHAR = PTR §< 



This sequence will set CHAR to the first character cf the array BUFFER. 
Although this could also have beer, dene with the more strsightf orward state- 
ment J 

CHAR = BUFFER[0] 

the use of PTR allows more versatility, since PTR could point to any array, not 
just the BUFFER array • Pointers and indirect operators are very useful in 
passing arrays and strings to subroutines to be operated on, as you ^iil see in 
Chapters 5 and 7. 

Note that you maj not use the indirect operators to identify the destination 
variable for an assignment statement- Therefore 
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- *- ' ; - " " - ^ i. _~ ; -r array M is discussed furrhc: d~ Lr.c ^ijlcn z:~ 
fl-:_:^-^r- • . ' / 2 and 7. 

variables- era aoroEi^/ declared fuse in ycer program, before the executable 

statements c These variables are e&Iief global variables ^ ^eeavse they can be 
accessed f :. :m anywhere in your program- Later another kind cf variable will be 
introduced called a local variable. Lce&i variables ar^ - ^ : i~ed inside 

subroutines, and are known only inside that subroutine Glc^sl variables are 
defined before any subroutines (or between subroutines and are known 
everywhere thereafter in the entire program, (including inside all 
subroutine?". This distinction will be clarified in Chapter z 7 where 
subroutines are discussed. 

Now that you know how to declare variables ar„d for^a expressions, you are 
ready to learn how to bring these pieces together with the reserved words to 
form statements , and then combine these statements into a complete working 
program. 
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DCTION 




Some P.r»Xl~JL c:z^ ^L^ta £._- 1 - _:~ ': r .merits in BASIC. Ic: sample, 

XV - Y . 

is an assignment statement, which is very similar to a BASIC LET statement. 
Howe v arc chete are some important differences between BASIC statements and 
PROK.r_ mt events, including: 

1- foreman: 5 io not "~ ".ins numbers. 

2r Only one statement is permitted on a line. 

3- A statement may not czzxipy more than one line (with the except io: : 
i~he D±Tr statement). 

ko Keywords and variables must be se.^ra^ad frc^ eatl". ozher by blani-c nr 

crher punctuation marks as required by the ? z^tem^z.^ * 

SlTMfzlX DIAGRAMS 

In many ways , PROMAL allows you a great deal more flexibility in construct- 
ing statements than BASIC. In order to help you determine exactly izhsz makes 
up a legal statement , a sat of s vntax diagrams is included in Appendix f= Tbeee 
syntax diagrams tell you graphically how to construct a. legal PROMAL staussi3~t . 
Syntax diagrams are not difficult tz use, once you are familiar witn. them. If 
li. the following descriptions you are unsure about & PB.OMAL statements correct 
ei^c^-:, you may refer to the diagrams in Appendix: ? the accomp?ry:* / g 

cisc^ssic«i of how to read them. 

PROGRAM STATEMENT 

Every PROMAL program must start with a PROGRAM statement of -he forms 
-or- 

OWMJlY .ISPS?] 

where laae is a legal PKCMAL identifier not used for any other purpose. The 
PROGRAM line declares the command name by which yen x-rill. execute the program 
when it is loaded into memory. You should always £&ke tiia PROGRAM name the 
sase £6 the file asss ycr, COMPILE <> The OWN keyword is optional, and is 

normally net used * If specified 5 it -"ill cause the compiled program to be 
loaded into memcry *:ith the global variables allocated immediately after the 
program, rather than being shared with other programs in high memory. This and 
the EXPORT and OVERLAY keywords are discussed further in Chapter 8 and in the 
optional Developer's Guide o 
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variable = expression 



the - T ari"Is cn r.he 1 zz*~ ~Ida~ 

The variable en the isfc cannot be a DATA iterc. Here are some sample 
assignment statements ; 

X=0 

ENDPAGE = TRUE 
SMaLLX -kIM(xI ? ^2 s O; 

-a:, ; "•" y> , : i * c ^~jldius [ i ] * RADirr ; z • 

Ysi^ssi - : > z .-i d y > z 

€SSZ:I3£AL 

A ccnditlooai statement is a statement r <hich alcers the cr:e: of execution 
of statements based cn evaluating a condition. In BASIC : the conditional 
statements are IF, FOR. . •NEXT, ON. . .GOTO, and 0^ . ,C-GS»JB~ PROMAL nas condi- 
tional statements which are more powerful and easier to read and understand 
than the related BASIC statements. The FROrAL conditional statements are the 
IF, WHILE, REPEAT, FOR, and CHOOSE statements. 

IF STATEMEa! 

By far the e:sc common conditioner statement is the IF statement . It can 

take several forms . The sidles t corn iss 

IF expression 
statement 1 
statement 2 

statement n 

In this form, the expression is tested, and if it is TRUE , then cil the 
indented statements following it are executed* If it is FALSE 9 then control 
passes directly cc statement n, on the same level of indentation as the IF . 

For examples 

IF X > 10 

OLDX - X 

X s - c 
z=x 



FALSE 
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EDITOR. 



- c taken any courses in progr.rrr • proba^l;* -are told 
i £ rs:r r v ;::> show a program**" s struct ur ??.~'L-JL simply 
rrfrrrss ;his eccic 5 ::- Jh? indentation does show the scruc:urs ~i ;r.^ program, 
fsrs is prrr&rl]r rite ^s&l rrirrrLamt feature :f ~frs rlSMkL Isnsrssfrs By using 
lrs£-._r.:.I^ r ar r ~yr ;rc ~.lral alaaent of the language, PROMA.L is rbl^ to do away 
with a Vs': confusing statement delimiters and begin-end brackets which 
pervarc c :crr structured languages* If you don't indent, you'll get an error 
message when you compile your program- 

A second fotr rf err IF statement has an ELSE clause; 

If expression. 2 

statement: a. r?r;i ^v^g- 



-y 



3 te. cement 2 
statement n ' 



In this form, the Indented stateserrs after the IF are executed if the express- 
Ion is TRUE, and the statements after the ELSE are executed otherwise. This 
fcrm Is used to select one of two mutually exclusive paths. ::r srample : 

IF X > 100 

POINTS = 3 
ELSE 

POINTS = 1 
SCORE = SCORE + POINTS 



If X is greater rrrr IrC, POINT? :s to 3 and control passes to the last 

line* If X Is not greater than 200 9 POINTS Is sec to 1 and control passes to 
the last line. 

The final form of the IF statement has one or more ELSE IF clauses before 
the final ELSE, for examples 



IF CHAR = 'D' 
DRAW 

ELSE IF CHAR = 'E' 

ERASE 
ELSE IF CftAR = ' Q' 

EXIT 
ELSE 

OUTPUT "ILLEGAL COMMAND." 
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one. 



11 may be "nested" to any depth needed. For example; 

if i: 



ELSE 
Y-l 

13 Y > 200 : 
Q=Y+Z ; 

In thie exaixirla ; saeh ccnoix^ all cos s ze iements with greater indentation. 

?cr exarpls v c 1^5 fir?;: "7 *'ot - ') 1- fslse, then control will pass 

iirec tr ?: = tsioer;f > « If ? -"sue- : 1 "r^Sc vhan s o&tement 2 decides if 
statements 5 end k should :e oxecoced rr snipped . The only way statement 3 
Till evsr fa cooso^ced is :Y ^z^zatz^ct is t-ae 5 cUut'if^- ^ 1b f^lse, and 
stetemeno 7 zs tri'Sc Yoc ^hoi:lo har^o rx doo-ct about which IF statement an ELSE 
"belongs to"; it is always the one with the same indentation. 

Indentation plays a ;iev role in making programs readable. You ^i±l scon be 
able to just scan over a PROMAL program or subroutine and immediately he chle 
to understand lis l:gic* Since PROMAL does not have a GOlt :: t^temcnt . zlzzxe 

will be no mystery as to how you get to a certain statement Yy jcso looking 
at the indents cion 5 you will have a "picture" of the program organization. 

YTf"~f- -~7i,T^5FT 

Next to If - 1Y1YY is one most commonly needed contr 1 stooament i^ 7 ROKiC o 
It has the relieving ferns 



WHILE expression 
statement 1 



statement n 

The WHILE statement evaluates the conditional expression. If it is TRUE-, the 

indented statements are executed, as in an IF statement. After the last 
indented statement is executed > control returns to the WHILE statement and the 
condition is re-tasted c The loop is repeated until the expression evaluates as 
FALSE; control then passes to statement m, which starts in the same column as 
the WHILE statement. The indented statements in a WHILE loop zz&j be executed 
zero or more times. For example J 



9 
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"T. S :-TT. At the 



>£r£AT statement is verv Lc ^ WHILE statement, except thzc -La 

i* :^s^d at the em :f th~ instead of the top. The EE PEAT 

statement has the following f \ _ 



REPEAT 

statement 1 — ; 

• I • lQ Vlfe^ 

UNTIL expression 

The indented statements are enScd-d one or mere times. After the firsc 
execution .: ::;:e indented statem-:- ;9 :La conditional expression is evaluated ♦ 

If the res ilt is FALSE, control p^ns^s '.ack to the top of the loop. If the 
statement is TRUE, control passes to the next statement after the UNTIL. For 
examples 

EE PEAT 

CHAR = GETC 
UNTIL CHAR = "A" 

GETC is. £ standard LIBRARY function I'hiah returns e key from the keyboard. 
Ther r f :nis loop waits for rn "A" zz ~e type 5 i ynoring all cthsr input. 

for ar^nsai 

The FOR statement is similar ': e 5AbI^ FGR-NEXT loop, tat is more restric- 
tive. A FOR loop has the form; 

FOR Iter = In- TO :ii 
statement 1 

statement n 

Iter oust be & \F£ri&bie of type T-JOSD, and Low and Hi must be expressions which 

evaluate to the lower and upper bounds for the loop, for examples 

WORE 3LFFLR [100 j 
WORD 1 

FOR 1=0 TO 39 
BUFFER [I] = 
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requirements, u-^ - c VHILE loop instead. 
CHOOSE STATEMEIF' 

The CHOOSI :.ic^8flt is a .r>^:-\ ly branch, somewhat similar to BA:1C~k 

Cr--£CSUB statemeoo - :he CA™ ^or-^ient :i rascal. _r : zc&. following 



iliOOSE expression 
. Dice 1 
s ictement 1 

encice 2 

■ ' ent i 



statement k 

Tiis iitOOSE statement -forks .a. ike ? oultiple-choi^e tsst . Tho expression is 
e :> ted, and eac:. ;f 'zz.~ : xl^ca listed belov: it compared oo oc in ~< cess- 

i:n, When a match is zv:zL z the indented state^enos aoe ei5Cj:ec ; If :o match 
is icond, the indented statements after the ELSE are executed (think cf :he 
ELSiu as "none of the above"). in any even; : ccrorcl always winds vp *z 
stateme' - 1- «-'ie first non-indented line "to-* ': n t I .loo. For example? 

CHOOSE GETC 

X=0 

START 

CONTIN 

X=9999 

LASTLINE 

ELSE 

PUT "Illegal key letter" 

Too prig-an fragment above inputs c character £o3x :he keyboard (f anction 

Gilo" o If ; he character is 'B " > ihan X is sec to I and the START subroutine is 
called £ and control transfers zc ;he last line If the character is "C" 5 

the G3KTIN subroutine is called instead, and control then passes to the last 
linec If the character does not match any of oka choices , then an error 
message is output (the PUT does this), and control passes to the last line* 
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RIGHT 
WOKD MUM 

CHOOSE HUM 

PROCEL . . 

2s+ 

PR0CESS_2 
ELSE 

PR0CESSJ3THER 

^szzj CHOOSE p'zp^exemz zLtt he simulated with an IF statement with an appro- 
priate number cf ELSE 17 clauses. However , CHOOSE will often be mo.;o i-fl^i^c 
since you do not ha~~a zz ^tell out each comparison explicitly. 

The CHOOSE ei^esc^:: :f_so has an alternative form where the word CHOOSE 
appears alone, fcr example: 

CHOOSE 
CHAR < ' ' 

CONTROLCHAR 
CHAR > $7F 

ILLEGALCHAR 
ELSE 

NORMALCHAR 

In this 1. rim, each of the choice- .-"^l^atec in Euceassiei until 
evaluates TRUE. If al^ of che choices £.r= r^L^E, rsi; tlo i^le^ted i Izz-^zaz-Z? 
after the ELSE are executed. This is ^zz^zzlj equips lar. 1 : zz e-- 17 wl~- « -r,:>..l 
ELSE IF clauses, except yen do net ha-s tc the 11"' 5 szplici :iy c 

BASH vsers should note fast alter cze Indents! Btazerzaizzrj are executed 
fcr one o 1 the choices , control automatically passes tc tr„e r Ir^ ion-indented 
z'zzzameu'z £ f :er the ELSE; you do rxt need to put a G1I0 aftar a^ch like you do 
for a BASIC ON-GOSUB. Also note z'z&t the ELSE Is mandatory, because ±z indi- 
cates the final choice ( 8I nor:a cf the above" ) . 

Sometimes It is desirable to "break out" cf a loop £.t £ rri" rthsr ;.han 
where the condit-cne.! test is done. The B1SA1C scateoent presides "hie capabi- 
lity for WHILE and REPEAT loops (but not for FOR loops I ; . For axsnple; 




13 3CBJS I 

2 

PR0CESS_2 

ELSE 

PROCESS C1---P 
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BREAK 




The NEXT statement is used to cause an immediate jump to the t i 

current WHILE or 'REPEAT loop / but not a FOE loop). For example; 

INQUOTE=FALSE 

COUNT* 

REPEAT 

CHA: - 3TC 
IF CHAR=""' 

INQUOTE=NOT INQUOTE 
NEXT 
IF INQUOTE 

NEXT 
C0UNT=C0UNT+1 
UNTIL CHAR=CR 

T::;lr zj - s--- -eg^nt counts the number r f e-:ai^^:srs -Jpsd cp to the next 
c&rriege return, excluding characters er -.1 :-~e~ : r v^tes (: deluding carriage 
re:,-_LS qu.ucee% The NEXT statements jess control ba.de to the tcp of the 

loop so as to Ignore characters in between ^snd ir.eljiitig) quotes. There may 
be better and easier ways to do this — this Is just for Illustration. 

NOTHXNG ST^SXSlCSi^'iL* 

The NOTHING statement does not perform any action, and the PROMAL COMPILER 

does not generate any object code for a NOTHING statement. This may seem of 
dubious merit; out is actually useful. For example; 

REPEAT 

NOTHING 
UNTIL GETC = CR 

This leep slnply watzs fcr a carriage return from the keyboard, Ignoring all 
. tnar chsrsccers . The NOTHING statement fulfills the syntactical requirement 
zzaz at least one Indented statement mast follow the REPEAT, but It performs no 
action, if yon tried to leave out the NOTHING statement, you would get an 
error message from the compiler. 
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SHORTCUTS FOR CONDITIONAL STATEMENTS 




¥crL = l^ 71^-: r: ~y : BYTE, 



IF FLAG=TRUE 

can be : I~ t ** 1 :L/ r-'-'_ . " ~r - --\-,: : -~ 11^ - 

IF FLAG 
Also the sequence; 

Ir >_ V " jO 

FLAG - TRUE 
ELSE 

FLAG = FALSE 

can be more econom:. ' " ittea as; 

flag - z , 

ESCAPE AND REFUGE STATEMENTS 

Tiie ESCAPE statement and REFUGE statement are unique to PROMAL and do not 

have a counterpart in other structured languages or BASIC • PROMAL, like many 
modern structured languages, does not have a GOTO statement, which results in 
much clseaerg iiore readable and more bug-free programs. There are occasions 
when yoc night wish you had a GOTO. This is bast illustrated by an example. 

Suppose you hat ~ --mplex application program, with many layers of subrout- 
ines* Suppose further tnsr £t sine low-level subroutine you come t: € ^oint 
where you need a piece :r£ logic that could be paraphrased as 5 

IF Disaster 

Print error message 

Exit back up to the top level routine. 

This is a common problem. Unfortunately, other languages do not provide t, **ay 
to "exit back up to the top level routine" . Instead, you must "unwise " all the 

CALLs with RETURNS • In other structured languages, you typically 98 gel- a" this 
problem '-y testing some global "Disaster" flag after returning from a lexfsr 
level routine to short-circuit further processing, for examples 

ilSUB ; call lower subroutine 
. DISASTER ; if had problem in LOWERS U3 
RETURN ; don't go any further 

Each higher level subroutine would perform the same logic, until yen "unwind" 
all the way back up to the desired routine. While this method works s it is 
unwieldy and dilutes the performance and clarity of the program with a lot of 
duplicate error checking o 
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REFUGE n 

ESCAPE n 



where n it c "~ ~ - i * ~ \ ~ and 2, allowing up to 3 different "refuges" to 
be defined ec ~r\:rrc-;tly it £ ?iAgle program. (Note: actually, t:.-^~- ir also a 
REFUGE 3, ':'.:>- -"-.e~ - - ? 9 r-r^-rved :c: £ rcecial purpose and is described in the 
optional £Z 7T Ei:?£?/3 1111Z) . Executing: 

REFUGE 2 

defines the statement afrer ir as refuge number 2. Subsequently executing : 
ESCAPE 2 

will :£^S3 .Immediate re-entry int^ t^re leat subroutine v or nain program' 

e>:eercrn§ a 1UGE 1 at ine line after the REFUGE statement, and will restore 
the c"£i:52i:: : : the subroutine a r ir at point. By resr :rirg context, we mt^ -r 
-iat Ell intermediate variables $ return addresses. ec?o, r ><hich would normally 

be "pending" when a RETURN is executed are discarded, up to the point where the 
refuge was executed** M ESCAPE is somewhat like a £EXT or BREAK statement; 
except that instead cf just jumping to the beginning or end of a loop, you can 
jexp tG amf^&sre yon^e oeem kforeo It is the programmer's responsibility tc 
insure that yea do r:t try tc ESCAPE tr £ 1~ e routine that has already 

returnee yrhich ifiil lea^ r e control in rrc-rran" s lane I ) Or. the next page is an 
example cf fragments cf a rrcgra'c usi~g a REFUGE and ESCAPE; 
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P10C ERROR ; v k-- -,A escape 

ARG WORD EE1NO 

BEGIN 

PUT NL, ERRCI'.i: rrj""^ % : -~*L ■ ^ splay message 

ESCAPE 1 

END 

PEOC CHECKCHAR 
BEGIN 

If CHAR <> LEGAL 
ERROR 3 

« m m 

END 

PROG PROCES SWORD 

CHECKCHAR 
END 

PROG DOPHRASE 

• • * 

PROCES SWORD 
E1D 

PROC DOLINE 

• • • 

REFUGE 1 ;Come here after error 
WHILE GETL(LINE) 
DC-PHRASE 

END 
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value* 



2. Both procedure zrA functions must be _ - "hive _*re 1 _ l - 

they can be c 

3. Functions and procedures are called by merely referencing their name in 

. ': -ment . 

4. seen procedures and functions may be passed ARGuments which they may 
operate on. 

5. Both procedures and functions may have local T-ES-l&Dle& which are known 

only :;ir'hin the scope of the subroutine. These local variables may 

duplicate other names outsits the subroutine ^nthc^t interference* 

Procedures and functions may be called recursively c 

lie ns now explain these concepts and show how to -r^ke effective use of 
suDrou ti.ies c 

JUNCTIONS AND PROCEDURES 

PROMAL does not have any built-in statements to do input anl output 5 like 
BASIC PRINT and INPUT statements. instead, PROMAL relies en s. of 

pre-defined subroutines and functions to preside input and output. These 
routines are always resident in memory, and are used by the EDITOR, EXECUTIVE, 
and COMPILER as well as programs you write a When you use these subroutines, 
they could easily be mistaken for a specie- „ s r a cement . For example; 

OUTPUT "Hello World! " 

appears just tine £ statement. There is no "CALL" or "GOSUB" keyword to reveal 
that this is really a subroutine call, with a passed argument of '"Hello 
World! "\ This is no accident. A design intent of PROMAL is that subroutines 
should give you much of the power of adding your own statements to the lang- 
uage. You call subroutines of your own in the same way* 

The built-in subroutines are described in detail in che LIBRARY MANUAL. At 
this point we would like to introduce yon to just the most important cf these 
routines c sc that y:j can perform basic input and output operations* 

Before you can call a subroutine, yen anst define it = For the LIBRARY 
subroutines , this is done by having the following statement near the top of 
your programs 
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SIMPLE 

Pi :-r; : - : _~ m c ~ -~ - > ' -f t v ~ = *::.ndar-* v r — r:: -- : *=• "l~ed PUT. It 

output- rinil- iar&ww«c= . r szztzg? c _he scre^r.- lc '.rr - "r or more 
argumer. f 1 r*: example : 

PUT "E-l; ~ -or It?!" FI 

TL1- -r^-.- ..-.s tie - IUT rv;:: 2edure an? t^-r€ it - r -o arguments to be 

-i splayed. The first* argument ie c^c Ruling ^i:- — In", and the second 
a^Lrent is FL :>e pre-defiiri "Valine " chaieit-r (~sich is the ASCII control 
character CI and has t'ns value ;:cr trb Apple, G:rr~dcr* version cf PROK^V* . 
Ui.li.ce a lrill~ 71111 £ ^ ~ -^0- ^rsu explicitly output an ML each time you 

c.'®&Z stcrt r Itrs ThJ £ sales li ~asy to build up a eomp-sitr line with 
■ ^veral cell? r o PUT 

Please noli trat., ^ri: <a 1- -It- y u cancel: prlrr cle numeric value " : f 
variable with the PUT statement. You can only print strings or characters. To 

print a numeric value, you will want to use the OUTPUT procedure. 

OUTPUT ^rocsdars fc: performing formatted output tj th<= screen It 

r~cepts one or more arguments- The first argiraest 2ESt fee c string 11 is 
called a format string, because it tells the format in which say additional 
rrgrre"s should be printed. If you have ever used a B^SiG version rl.i z*r 
supports PRINT USING* OUTPUT i& similar. Act^lly- it 1? *iosc similar ro the 
SHlrTF function in the C language. 

lie 9: ring contains text to be printed on the screen as well as 

f crmatting information. The special lead-in character : ~ is used to start a 
field specification (sometimes caller s field descriptor) r which tells he^ ?o 
print something. For examples 

INT SECS 
• • • 

SECS = 673 

OUTPUT "The answer is #1 seconds." , SECS 

These statements will displays 

The answer is 573 seconds. 

The value of the argument SECS replaces the format field specification #1* The 
"#1" indicates that the second argument should be displayed as an integer. The 
most commonly needed field specifications include; 
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#w 

#H 

is 
#c 
#1 

#R 



OUTPUT '7/C//W decimal = #?: h =:xadecimal . " ,N,N 

will display; 

~ : a_l - 1 ! : "- ex ad ? : n- 1 = 

afi^i- c "^: : te. Ictica .;hs #C does not go with any argument i: 

jr . : - L-:.:z 2 € rs*::r- 

: - - : - • ' s width" in the fornix _ c r„g (for example, to 

ma/sz of nmuhs^s _ir.s n~ *' c These options are fully describee! in the 

LlESi.RY i^J^aL- For REAL natpn:;, you normally specify both a fie 16 -idth and 

the numb 2 r of c-s-in^l places t :• displayed, In the form; 

#w.dR 

where w is the field width ;f.c,x « ;x 11 —aracters) s anc i is the desired 
number e-f c- seimal places* Tor 3X£2.pl? ° 

REAL BUCKS 

BUCKt - 175 -1C 
OUTPUT 7 >5# T , 2 ?. " , BUCKS 

wi_ : display; 

8 276oIG 

whereas BASIC would always print S "S-l instead. 

siistz tz?ut 



Now that you know how to output to the screen, let's see how you input from 
the ksyhc^rd- The procedure GETL is used to get one line from the keyboard and 
sccrs it in su air.e.y a soring. GETL allows all editing features (backspace, 
insert, deists, CTRL-B ; etc) allowed by the EXECUTIVE- It returns when the 
RETURN lc€y is pressed. For example; 
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GETL LINE, 20 



"111 c a l:..r^ frcr. ' cz *37 board u_: ^ l:,r, 5 . -r..iditional 

characters cl :he 11 :;a "fill la Ignore! - 11 the sec:;;.: rrgrrieirt Is :nct 
^ - ~~ -I - -1:1 t < ^.ax?-:rrr of 80 c^oi^olir^ 1 ... l~rrrtc 

Ire ' -1 'II. 5rsr:eiren-; Is riccl more rcr- erfrl tl.oii 1TP1T statement 

because GETL stsppores a collate set of 1 i-e-edi^i.ig &e>-s. as snown in Table 1 
cf „hc USEES Hi' t T i.1 Hire leys are I.-rrer^ -111, :re Hltl^g keys used In 

the PROMAL EXECUTIVE and EDITOR. 

Or: a of re a mc 3 ~ ireful fe^rare^ zi GETL If tie ability to recall prior lines 
by pressing CTRL-B. Another powerful feature for Lianj applications is the use 
of function keys to "call up" pre-defined strings of up to 31 characters (much 
like many commercial "keyboard enhancers") . The LIBRARY MANUAL describes how 
to use F KEYSET to define a string to be substitute! fcr a function key. 

NUMERIC INPUT 

How do you read in a rr^nerlc ; v c.lue from the keyboard? This is not quite as 
simple in PROMAL as In B-iilt- recuse PROKAL does cct have a builc-ir. statement 
to read a number • Inst eel •> s " In : r rr - parts. First, you read a line 

Into a buffer as described cbc^e* ;!:_sn .you convert the value represented by 
the string usl-g f vac tier: :i 1TRREAL. STRVAL converts a string 1c the 

numeric value It ~2presert£ cf type I IT, or WORD. STRRE-fl is csel tc pervert 
type REO ^'n-rer^ « It is similar to the BASIC function ^"ALo Far e%afrple f tc 
read a number called HEIGHT from the keyboard, you coulc >rrlte; 

byte e - 

mm HEIGHT 
BYTE INDEX 

GETL BUF 

INDEX = S TRVAL ( BUF , #HE IGHT ) 

The STRVAL function expects at least two arguments, The f Irsc argr.r-ert Is the 

address of the string tc be converted • The second argument Is the address or 
the variable to receive the value. To specify the address cf the variable 
(rather than the value), you nee d to specify the # operator, as shown above. 
Forgetting the # in front of the variable is a common error that results in the 
value being installed at whatever address is the current value of HEIGHT, so be 
careful! Also remember that the destination variable must be type WORD or INT, 
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and variable number 3 :f inputs on a line. These options are described in the 
LIBRARY MANUAL . 



BASIC users 33cust~r<=d \ rslrg the IN PL I 1 c^xe.'" .0 :,: m ; t l^z * rrrirerlc 
input from the kajrrarc a 7 ",! f ::,r,., ^ It r.ay Wc..:c iicor^or^cs che :::",lc v :r.v 
general purpose ?±C¥lKL rouciis, This IMPUTE functicn %r£ll gi^~ e prompt fcr 
Input and return the HEAL rsl-ie -hat the uear inters Zzo± ^e^be^r-i- If an 
illegal Input is entered frca the keyboard, ft repeats the prompt * 



FUNC REAL 1P7 3 : fr^nr^ 

; Prompt fcr nrrteric f nrr;: :rom keyboard return one REAL value. 
ARG WORD PR" 2:1 L ? LesiraL cr^opi 
REAL TEMP ; Talus to be returned 

BYTE INDEX : Index zc # chars scanned 

OWN BYTE ELF ~ 21/ : Ie<np buffer for ryped input line 
BEGIN 
REPEAT 

PUT NL, PROMPT ; Display prompt 

GETL BUF.2G ; Get typed Input 
i NDEX= S TRIBAL ( BUF , //TEMP ) 

IF INDEX=0 ; No legal digits? 

PUT NL, "Please enter a numeric value" 
UNTIL INDEX > 

RETURN TEMP ; Return value typed In 

END 

A sample program fragment using this routine fcr input might look like this; 



REAL HEIGHT 
REAL WIDTH 
REAL AREA 

HE IGHT= INPUTS. ("Height of triangle? ") 
WIDTH = INPUIRC "Base of zriangle? ") 
AREA=0. 5*HEIGHT*WIDTH 

OUTPUT "#CArea of triangle Is #12«4R square anrts^C 19 , AREA 
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"'her. y ^\ C ^ lea y own PROM~„ . subroutine, you *r* c ; ~z i _ lowing 

g e ~ r £ jl f v r :i ; 

{lieadesrj- 
- erjrr^eirts} 
{l©eel r ariablf=e ^ 
BEGl!*' 

12IB 

The {he£i«i"r is ^ -rlr^ls, line the": identifies the ste_ i of* tia subroutine, 
it has the fcrx^ 

PROC name 

or 

?US^ Type lame 

v -rich ce ;ir:es whether the subroutine eill : o a procedure r function, for 

example : 

PROC SORT 

declares the start cf e procedure celled SORT, 
FUNC BYTE TESTPORT 

declares the start of a function called TESTPORT which will return a value of 
type BYTE. The type returnee ney be BYTE, WORD, INT, or REAL « 

Tie {^rg-jserits^ end {local variables} will be discussed very shcrrly**- 

The {!?edyj rare of the procedure or function is contained between the ESfSIST 
and 11B statements = lo contains the executable ct sterner t? ~f rlee procedure or 
function* When progren control reaches the END statement, the subroutine Till 

re tern to the calling program. Optionally, the RETURN statement can be used to 
return before the E1D statement • 

For FJNCtions, a RETURN stsoesent is required and naest be followed by an 
expression which evaluates to ohe value to be returned by the function. For 
example: 
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ARG Type lame 



-i-- casired data type which may be BYTE, INT, WC?.I : s- \.tll - ~%-se is 

las v*~-s rame s-f she subroutit.^ r r r-red in the same wa •* ~ * s ': u sr ~ ra ar:,^3le 
names • 



For exam si -a - 



PROC SORT 

ARG WORD N 
ARG WORD PTE 



• eclares two passed argument : i> and P r «ll ; ^ocr -jf cype WORD. The order in 
r±dLch t::e arguments are declared is the ssse ss the orde*: in which the eorres- 

rsnding value? rsill "is assed. For example : If the SORT procedure above was 
-ailed with? 

BYTE ARRi . ] 
• • % 

SOR: 11. JLIOAY 



then when SORT begins executing, N will hav-. zh^ valu..- s .: Is 3 nd PTE will have 
the acdra-3 sf ARRAY. As you can ses < a srcscdure is sailed >y simply writing 
the UEie or tire procedure to be called. Arguments are passed by putting the 
arguments af :ar the procedure name. Each argument 2 an be an expression, and 
arguments era separated by commas . When you call a procedure or function which 
you have defined, the number af arguments must agree exactly ritr tha number 
you declared, or you will get an error message from the compiler. The initial 
value of the arguments depends entirely on the values passed. 



If the routine is later called with: 



SORT CURSIZE+1, BUFFER 



then N will have the value CURSIZ1 -I and PTR will have the value BUFFER. As 

you might imagine , this substitution process makes subroutines very versatile * 
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Z=N 

After the SORT zzkl-^.^ rartr^ "ar": rill ".r ihr ^lus cf 1 -"a a; i- :z nigral 
to Z? Wirt ir ?~ ~1 t: v-;..: i*- . c t-£^e Z" 11 a. ^ sr: rsa ^rlstt- 

tutea r^r 1 in ths SCR~ r-^tira? lis are-er is rha ~ M "ill^ £-.,11 ra -1^ 
' f ;^?:3- t a- Z ir „c s subrouti : ~ la only meaningful wit hi a :::ta subroutine where 

it is declarer. 

rllltal ;ds^es s^L2£:t- r a "rail r ^atra * .££i: t "t~.\ air .rri-iLca lae — a 
: a ^ha rrirre rracass ^r^s tar rrrare s ::act .. This aa - as :r a : ^*aar ta-w pass ei 
argaaeric r„ ??Cii^l 5 lie as roala^ral aaa rLir ^zZsz i - ta ^ f:r 

aha tcc^t -^ariari- Ir.arrfcie^ r f raa lac&l ""a^iabli^ valae is aicarsi airhir 
rts sabre acine^ it rill not affect the -~aias :c era calling routine-- ?c: 
example, suppose that part :: car SORT routine looks like I:his i 

P10C SORT 
ARG WORD N 
ARG WORD PTE 
BEGIN 

N=0 

Assuming we call the subroutine with : 
SIZE«17 

SORT SIZE, BUFFER 

Wi.ai rail :a the value zz SIZE when the subroutine returns? < ? ill a: still be 
1" or Till it be 0? It will be L7 ? because iaa variable N is local to the SORT 
routine, and contains a copy of the value zi SIZE, not the SIZE variable 
itself. 

A passed argument need art have the ear's ijpa as the type declarec fcr *:ha 
variable in -:he subroutine, although in gaaa-ial ic is good practice tc nahe 
their- zhe s&ae. If you pass a BYTE arguraer a cc a variable declared to be a 
WC?H <, the "alue will be converted to a WC311 as i:: is passed. For exacrirs 

BYTE SHE 

SIZE- 10 

SORT SIZE, BUFFER 
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M[PTR]=0 

irrgrxsr^s zr^sz csrdsrr: tt sitipd^ : u,cUck;- ::.>i:s-i' ^silshlss. 'drt: 
not declare &r§'jaast tffcier? is us ^rrsr^ dhids drse r.ct naar ifcst rnu C2~^t 
series £ global f r~ i. i.isld^ £ subrrccdrr . 2': ;:. d:, Zeis ::&^ : . Tec 

carpet deelsra rhs arrar inside ths sjd routine- 1, r = ^ ~ •:- possible for 5. 
subroutine to cpsr-sts on an array v/hese address is passed ss sr: argument- It: 
our example procedure* SORT : zaa array BUFFER was gi^su as the secoad 
argument. Rese:rdar zhsd: ":/ha^ ail arrsy iraisa Is u^sd ^ithrai e subscript:. PRGtiAL 
gsneretes the address 3f Ih&c arrays Therefore our cell Hill rass the address 
" • d :d.:e arr^ / ; :. ->c= s^SL^rdri : -^dfrd Is * dy did : e dad £ 'ad r; da a \ GRr 
£irc€ PTR co^tdn.? the address f " rs sds^i : d rs £r.:ry ^ elements of the srrray 
can be acces-^d asdr? rha i'idirs:-.r cpersrrrs. :r dy ds if £1:27 ,-.r snovjn 
above, for example : 

BYTE BtJFFd ' " 

PROG SORT 
ARG WORD 1 
ARG WORD PTR 
BEGIN 

IF PTRK r • 
END 



SORT 1 3 ; BUFFER 



The IF statement above will compare the value of dhe firs: -Lid second bytes of 
the array BUFFER. 
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See BLKMOV in the 

local WMLimms 

A local variab': ~- :> - • ailar to an argument, but has mo ir,:__i~.l '".il-. v 
defined* Local variables are known only within the subroutine ir: T -\.±c:i 
are declared., and "disappear" when the routine . e turns . Loc^l ~~a.'£±a.'2l^z z r - 
most of can used for temporary storage within the routine. Lcc-L l-^l.l.i-£ 
should be declared after the last ARGument in the procedure cr iiL:izzzzvi~ V 
local variable declaration appear - uhe same as a simple globe 1 "ariable 
declaration* ?ol example : 

PROG SORT 
AEG WORD N 

A1G WORD PTE 
WORD 1 
BYTE CHAR 



, lid Lluli! 



declares two local variables , 1 arid CHAR. The compiler knows these are local 
variables and not global variables because they are declared within the subrou- 
tine. Except for having no initial value , local variables behave identically 
to arguments * in particular, they are allocated on a stack and therefore must 
be simple variables, not arrays . 

To illustrate the concepts of global and local variables , here is a com- 
plete, simple function which returns the number of blanks in a string. Remember 
that a PROMAL string is an array of bytes terminated by a $00 byte. 



FUNC BYTE NUMBLANKS ; string 

; return # blanks in string 

ARG WORD STRINGPTR ; address of string 

BYTE N ; counter 

BEGIN 

N=0 

WHILE STRINGPTR@< 

IF STRINGPTR@< ' 
N=N+1 

STRINGPTR=STRINGPTR+1 

RETURN N 
END 



There are a number of important concepts here. First s the line 



WHILE STRINGPTR@< 



will evaluate TRUE as long as the byte pointed to by STRINGPTR is net 0; that 
is s not end-of -string. Second, the line 



STRINGPTR=STRINGPTR+1 
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string one character at a time. 



RETURN N statement. 

If , -. - -, ? -rr 

■ L'i'JtiBL^iv .1 ' '"he .lv :ur,:e a^ery I : ay ? ' 

the:. "1 rill ze £ei :z :, 'z Zzzzzz zc^l f _r o :i __ A s, r^ilUe procedures , must ;e 

cal er — ;r - r f -~ ?ri*. r* :. ' - =: rr ^ ^rrr: r - ? ~3 - Thi- ir because a function 

can, he ~a~t i c 1 ~ ' c c. -~> - -•- .-^ <z- ^ j f- t"_ _ ~ " ~ / c.."^-^ -£•_-'-• 2_ 7, ° 

GETL MYMSG 

NBP1 = MlMEL.lh^"113L^ - 1 
"ill 5-r - Hi: to S'h rcmler _ - Hanks in MYMSG plus 1. 
3z¥ ' 7 .1.S.Ij^!:M 



Iccai variables may not be arrays, and the value associated with a local 
variable, "disappears" upon exit from the subroutine in which it is defined 
(because space for the variable is allocated on a stack). This meets the 
requirements of ma tes: rsjcrity of variables in subroutines • Sometimes 
though, you may waaz cz have a variable known only within the subroutine, but 
which is an array or needs zz preserve ±zs value from cell to call. This can 
be done by declaring an IvIN variable. For exancrle, tie statements; 

OWN BYTE TEMPBT1 i ~ 
OWN WORD COUNT 

declare two variables whose names are 1 : c s 1 z : ::he subroutine in which they are 
declared, but which will maintain their values through rroitiple subroutine 

invocatic rs . The most common use of OWN variables is rc provide a scratch 
array reeded for Intermediate processing by a sutrcrtir,s- 111 7 variables should 
be declared £if ter ell argmancs and local variables, but before the BEGIN 
statement ir a 3 coroutine 

GOOD WmGm^JMlEQ PRACTICE rlTH SUBROUTINES 

Iz is considered good programming practice to add a cornnent after the 
header line of a procedure cr fraction definition Thiol tells the function of 
the subroutine, "rhat it expects f cr input , wear ir returns for output ? etc. 
Many PROMAL programmers like to put a comment a; the end of the header line 

listing the required arguments * If you do this , it will be easy to refer to 
the header line for a quick reminder of what arguments are expected, finally, 
it is a good idea to put a comment on each argument declaration and local 
\ r ariabie s identifying the purpose cf the variable and any constraints on its 
use . 
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c'-l'T" *?i*~ =S Ti^t"? 1 ?. 'he ^ aiLr, €.? " cU" aabl^ 5 6 - 7t 1,5 »jf JrL c ~r ^ T -1 "Lt^t 

tc pick a vert ~-hier describes the cain action cf the subroutine for its name- 
Than T - T her y*n c^ll the subroutine \ 7 ith ^r tor? -rsu^ercs rhe starataent 

will be very readable c for examples 

DISPLAY SPACESHIP 

calls procedure DISPLAY wirn an argument cf SPACESHIP. 

You can learn a let about procedures and functions by studying the sample 
programs on the PROMAL diskette r 

RECURSIVE 

PROMAL fully supports -eeursicr. This means thec it is permissabia fcr a 

procedure or function tc call itself 5 or for procedure A tc call procedure B 
which in turn calls procedure a again. This capability i5 very xmpercanfc in 
certain programming disclplirB3 ? such as writing compiler* ; rrtifioi^l irreill- 
gence applications: and in symbolic math. It is also passible tc have forward 
references to procedures and fractions. Techniques for recursive programing 
are described in Appeals Jb 

The ability to perform recursion on the Commodore 64 and Apple 11 is 
limited by the architect are of the 6502 processor, which only has a 256 byte 
stack. Although PRoMAL has bear carefully written to work around this limita- 
tion as much as is practical 9 ycu should not expect too many levels of nesting 
(cr recursion) before yon get a STACK ERROR message. You will use up more 
sraek space as the number of local variables or passed arguments increases. A 
typical function with one passed argument and one local variable can call 
itself about 40 times before stack overflow occurs. This is why it is possible 
to gee a stack overflow error while compiling a program with an expression that 
is very complicated and uses many levels of parentheses. The compiler uses 
recursion extensively to parse statements and can run our cf stack space as 
repeated recursive subroutine calls are made to process complex statements. 
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- -~ ?- ~>r-i^ i rv_ ; e -i : " :!• - t -"I \~ ^tire program at once. 
* - ~ - . : cr.-r : ~; £"^ r r y~r~ -jrc-- c Lr. - v-'eral files. Your 

— -r^- :**->z. ZJ.Lyyi ^^tec^n- ~: -id ?I - e sub-files. You 
- ^l::^I "^n I-^LICE r^^ner.;: -5 ^af ' - ir^lude the LIBRARY 

~l! llzc^d I:: /c-jc .p'j-gL-i^. lo'- dc r ,c» ,r- I *I :_ e - for your own programs. 



"Il.i I..-, icjrsil&i ~c ps„~e at: z':z\. : zzi^z zz. The : : ;.. Ii zzd cr~p:Ivs z . 

the lines in the file FILE? "J3S r S before continuing. 

You may put an INCLUDE statement anywhere you can put a declaration. A 
".S" extension will be assumed for the file name if one is net specified. The 
INCLUDE file can have a drive or directory prefix. For the Commodore 64, due 
to limitations of the Commodore 1541 disk drive, you cannot have nested include 
rli.es • that is, a file INCLUDEd in the compilation canno; itself contain 
another INCLUDE statement). For the Apple II, INCLUDE files may be nested up 
to 3 deep. However, you may need to specify more than three buffers for FroDOS 
(see the BUFFERS command In the PROMAL USER'S GUIDE) In order to use nested 
INCLUDES . INCLUDE statements car also be used to import definitions from 
separately compiled modules, as Is described later In the LOADer section. 

ENABLING All DISABLING LISTING OUTPUT MITE TEE LIST STATEMENT 

The L option on the COMPILE command Is used to enable listing output for 
the compiler. When making a listing, yon can also disable the listing for 
parts of your program with the LIST statement. The LIST statement can appear 
anywhere a declaration can appear. It can have either of the following forms J 

LIST Constant 

or 

LIST 

The first form enables the listing If Constant evaluates to a non-zero 
^alue and disables the listing If It Is zero. The second form restores the 
listing mode to whatever It was prior to the previous LIST (on or off). This 
form is useful at the end of a subroutine package which has the listing turned 
off, where It is not known if you will want the listing ON or OFF after the end 
of the subroutine package « 

You may have any number of LIST statements in a program. If the L option 
is not specified on the COMPILE command, no listing will be made regardless of 
any embedded LIST statements . For an example. If you TYPE L, you will see how 
the listing of the LIBRARY is disabled. 
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: _ ~ - r- -~ « ^r^r « ~ r: % 'i vary only 

^1;.^.-; ; i: --i/r^:-'* \ - " \~ ^ 1-lh 11% . 1- sl^^i _y different for the 

i~ CX ~'/r~ - ~*v?lc~* :• . t-~ ~ - — i 'ii' eh:. In .^ecs 2-1- .Lis, you may 
r; ^''^ - i~-£i-.r>-£^ :f ~?/>"4"l *~ iC^^z^jlI „ ^s^sls'tf,^ capability, 

nil ;lc r~"» j ~ ~r.rl~ ;;ior y:r tr gsr„e^?,:^ - - ^ v; *:1 -~ ions of a program 

f re ~ ~ nti 'earners '"rich I_~CLlI5rr - ly ^r^rf r ying which version 

- ^isr ; ' : ^ir^il c : -, t- - P TT -r r ; rc- r 1: . ~ . - - h ~r~ -™ works. 

Z^:;. ; : - c. ir. sour _ - y - : i r ^rr ~ - '1 rr : ~hihh 

; dy li '.cii^ll-:' £r .: a certa. a n - :>i ~ r- In:. - 1-3 1. c s by ^rcirtlrr a 
lice above tha first "srsion-depender line, containing 5 question ;:sr> in 
iciuui one fcllcrv/ed immediately by a single char an tar raprasenring chs "arsion 
for which the following lines are tc be assemble! - Fci example, you -night 
choose ^A" for an Apple-dependent portion and '"0"' for a Commodore-dependent 
section j 

PROGRAM MYPROG 

INCLUDE LIBRARY 

>A 

PUT NL, "The COLOR command is net supported on the Apple." 
? 

?G 

C0L0R=NUMVAL 

? 



In this example, there are twe conditionally compiled blocks 5 each cf a 
single line. The first block is started by the ?A and is only intended tc be 
compiled if we want an Apple version The ? oy itself (exactly in column i) 
terminates this block. The second block is started by ?C snd. terminated by 

the second plain ? character • 

Selecting which (or neither) block should be compiled is selected by the ? 
(version) option on the COMPILE command • For example, 

COMPILE MYPROG V=A 

will cause the Apple version to be compiled, and 
COMPILE MYPROG V=C 

will cau^r the statement C0L0R=NUMVAL to be compiled instead. If you don't 

specify either V s C or V=A on the command line, then neither block will be 
compil - .. a 

Conditional compilation is sort of like a simple IF statement, except that 
if the conditional block is skipped, the compiler does not gener ate any code at 
all for those statements; the result is equivalent to removing them with the 
EDITOR (or, more precisely, to "commenting them out" by putting a semi-colon in 
front of each). 
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for 



~ y ~ — 'I - ' 

?AC 

starts * ?-r-iitional block which "\: \ cr- :: r.l - vr f ^k - ; v: 

specif i * ut won't otherwise. 

If no ? option is specified, the compiler \" 1 ~ c ~-vt l- a block whitk ?^rrts 
with 

?* 

~~ r : appears* This Is useful for embedding an error message to remind the 
user thai a version nice t "be specified on the command line. For examples 

PROGRAM MYPROG 
?* 

*** YOU MUST SPECIFY V=A 01 V=C TO COMPILE THIS PROGRAM! *** 

? 

INCLUDE LIBRARY 



If you compile this program without the V op _ - -:. :ified, the compiler will 
attempt to compile the warning line, giving ac: error message and displaying the 
line. If you specify a V option, the warning '"Hi not be compiled. 

You may have any number of conditional blocks in a program* However, you 

may not nest conditional compilation blocks (that is. you can't have a 
conn i tic- :rsl kisck inside -notker coed I clonal block) The aiss cf a conditional 
block is arbitrary., arid may span INCLUDE files- It is your responsibility to 
insure that each block is terminated by a ? in column 1* You may have any 
number of single character version indicators following the ? character tvhich 
begins a conditional bl^o~ : y o ,: ~i?.y specify ^iily c-ne ch?recte% en the 7 

command line opclon ;i£ yor. specify iera^ all kec the first character ^ill be 
ignored, so V=APPLE is equivalent to V~ik - 

The RELOCATE eS file en the PROMAL SYSTEM DISK lllusf rates the rse of 
conditional compilation* 
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imodore 64 computer hardware. 



ihe PROMAjL Utlll Xlta ~ a ~~z':± ^a n '1- 

using PROKr.^ _jLle^ £ : c-%~"a^&e :;a a: a.: .^viaa ar . 

material, particalarl; 7 raale 1 lalla a. before proceeding aa th ills 
section, which ; ascribes ;,c--' tc la pat cac crtavt t: fllss aac ae~-LC3£ f -'c-a 
within your PRC-LAI. : t .^a-aa In ^ai tic aler- :l£aaa raasabaa tlac file 
names normally ha^e at least aac caaracters- whale cables .^srues aa> e & single 

character. Also T^srl^; tlac da sys tea rill nsa^lly ssaaaa s asfaalt 111:, 
extension of ".C" for file naxas if ac rile ezcsaslon lr specified- 

rlClir.l provides fa-: : "I-'- is aa-i pa; ceca-ces la Ice ltlc-J?i tc iapac aac cta't 

te Hies ana de-ices Tba saaie a::- tir.es sajr ba ased a a aeasas a fsle ar 

aealea f cadi aa ti& aaiataab ~ 

aaSZHie MH? CLSsf XSS ?113S 

Before a f^lca c r 1 s"nLce can be accessed, it xmaz be opened . The library 
fa act ion OPEN per f eras this -ask. The OPEN function returns a file aamiie 
% sometimes called a ills lesoriptor), which is a pointer to a table maintained 
la memory by IlCMal. asec tc cantrci file 1/1 This file handle should be 
assigned to a -irariabla of type WORD. Once the file is opera the file handle 
can ha used to direct aab sequent 1, ^ ;e taa ilia desired. For example : 

WORD INFILE 

I1T111 - 0?EN( "MYFILE . D" , ""SI" ' 

cpeas fiie fiTFlLE.D fca reading The second argument mast la cf type BYTE (not 
sirring: " a; -a Indicates ths mode cf operation, chosen from the fallowings 

'IS." (ea ositted) Open the fole for rsad access. 

~W Open a new file for write access. 

"kf Open an existing file far append access. 

"B" (ICet available cm ~ *dara^. Open for both read and write access • 

if taa file asmile is reraraei ss G 9 than alia a^ea was act sacaaesfai ? aai 
an at a: a cede Is available la a globally predefined a a rial la called ICEEROR. 
ICERRCR '-ill be one of ths fallowings 
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IOERROR Meanins zz,> * ^andl^ ~ ^\ n:^ 



rig volume na\: . . I^cL^ 



cces:-- s'^rs • : 

oo many op sr. Itl^z ) 
ected disk ('W or "A" recess) 

disk manual or Apple ProDOS manual. 

You should always test for an open fEiIrre before attempting I/O to the file or 
device. For example; 

WORD INFILE ;file handle for inpuc file 

• e • 

INFILE « OPEN ("MYFILE.D'VR") 

IF INFILE = 

IF I0ERR0R=4 ; the most likely error 
ABORT "MYFILEe D file not found." 

ABORT "//CDisk OPEN error #W M , IOERROR 
; Open was successful . • . 

• • • 

You can also open the devices for Input or output in the same way, for 
example : 

INFILE = OPEN (T,T) 

opens the Workspace for read access. Recall that the Workspace is a single 
in-memory file with a fixed maximum size (variable size for the Commodore 64). 

WORD PRINTER 
• • • 

PRINTER=OPEN( "P" , ) 
IF PRINTER=0 

PUT NL, "CANT OUTPUT TO PRINTER" 

opens the printer device for output and checks the file handle for a successful 
open. 

FUNCTIONS FOR FILE AND DEVICE I/O 

Probably the aost commonly used routines for accessing files are GETLF and 

PUTF a Function GETLF gets a line of text from a file or device, and procedure 
PUTF outputs characters or strings to a file or device* The first argument for 
all file-access routines mmimt he the file handle of che previously-opened 
file or device. Function GETLF returns TRUE If It successfully got a line f and 
FALSE If end~of-file was encountered Immediately. For example : 

WHILE GETLF (INFILE, BUFFER) 



Liiegai x j 



7 

Other 
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Procedure PUTF is similar to the screen-output routine, PUT, except that 
th- r:r'" argument must specify the file han ..• o r recess fully-opened 
;:ila or device, for examples 



WORD OUTFILE 

OUTFILE = OPEN ( "MYFILE . T" , ) 
IF OUTFILE = 

PUT "Unable to open MYFILE . T for output." 

ABORT 

PUTF OUTFILE, "This line goes to MYFILE. T" , NL 
PUTF OUTFILE," So does this.",NL 



Like PUT, PUTF can contain any number cf strings or sln-li chaiaot^r argu- 
ments to be output o It will nor. output a carriage return unless explicitly 
indicated. PUTF can put any kind of data byte out to a file, not just print- 
able characters. 

The OUTPUTF procedure is equivalent to the OUTPUT procedure for formatted 
output , except that the first argument must be the desired file handle •> For 

examples 

OUTPUTF OUTFILE, "IC-E #S" , LINE NUM, LINE 

outputs to the file previously opened. 

Other functions are available for single character and block input-output 
to files and devices , These are described in the LIBRARY MANUAL. 

ST BIH ABB STBOUT WJIE 3&KBLES 

When your PROMAL program begins , you already have two open file handles 
available for use. These are the globally predefined WORD variables STDIN and 
STDOBTo By default * these file handles normally point to the keyboard and 
screen f respectively « However, they can be redirected to any file or device 
when your program is executed by an EXECUTIVE command (See the MEET PROMAL and 
PROMAL USER'S MANUAL for details). Therefore if you /input from STDIN and 
output to STDOUT 5 your program's output will be redirectable under EXECUTIVE 
control o For examples 

PUTF STDOUT,"This goes to the screen or where I redirect it*" s NL 
PUTF STDOUT,"So does this/' 
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OUTPUT TO PRINTER 



To outy-^' *i *.".^ -'-\-f--. f r ,rb r t i- 'I* " : - \ iy — r- - t; v 

fib- ?aty:" ~ ^ ^ - b : ^ •' t: c r- _ n y— r r ; • ' : r - r 

- 1 r ume a t » T" ~ examp 1 e : 

WORD PET ; Handle for printer 

REAL X 

PRT^byiy "?" .' < v ; Open ynyr for writing 

IF ?RT - : 

AdCai^ ^c-Ji-at-o open pr Ic;s : - 

PUTF PRT, NL, "This line gr^s -he printer," 

X=124.35 

OUTPUTF PRT, M #cThe answer is #12.4R",X 

Kote zhac y^sr "because you were able to OPEN the printer successfully does 
not necessarily taear. the printer is ready to receive output* If you OPEN the 
printer > send it output , and the system appears to hang- it may be that the 
printer is r»ot cr-iine or ready to print. 

For tee CossE^dore 54 ; you muse reaa-rbsr ~: t 1 : cc T :sr cr. tire rriryer v"hils 
EYMOCISK is or, (slsc, for interfaces sact as .he CAxBCCj the interface susc be 
eff tc=c; fcr the 3 ARD 1 1 ir.:srface : ibis r^saa ri^t the ai.rg^e wire xrst be 
ynpluggec frox the bach c f rha computer -bile bYFOblSX is? — Y^r lar y\..:\. 
ITlTCblSK on and ^bb brom within a y: ogr^ - if bsei^ei .;se? ^y 

When doing output to a printer, be srxe to send a NL after the last line, 
since many printers keep the line i:r t ,eir internal memory until & CI is 
received tc cause them to print. 

Printers vary considerably in terms of interface to the computer. To help 
reduce the difficulty in dealing with various printers and printer interfaces, 
PROMAL pre-defines several variables (in file PROSYS.S) tc govern printer 
output* 

For the Apple II, you can control whether or not PROMAL should automat ical ly 
send a LF after every CI tc your printer. See APFEHDIX 1 for details . Also, 

if your computer is a lie cr is connected by a serial interface, you will need 
to set another variable tc perform graphics or escape sequences* This is also 
described in APFEHDIX E. 
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■■r.u .....oUU:;,. .^fcUisJf^ bj&^^-iiw^ 

fre^er.: e ; ^ as ^ud^rli:; f u£ . font cr^ra^^r 31.se. / : • 

Zz Is very eas~/ to sezd t*~ess sequences to the critter using PEUhAL PUT? 

9cs *zs-za-z% : alzar you • s se~ u: vgua . :: 1 :z:e.: .... ;u:trcl options j,ro parly £,s 

c escribed above <> ?or example, if your printer ^eiiueI tells you ti&c the 

;:srci"j:I^r 55:^^5 ea; 5::r y~u - 7 ?u: is: 

Escape sequence Decimal ::rr r ; : B^SIC fcrx 

ESC W 1 <T - ^ LPRINT CHES{27) ?CHZS ' S" * ;CHR$f - i ; 

then in PROMAL you could just write; 
PUTF PRT1 27 s 37 : 45 

assuming you have previously epsaeet the "P" device with handle ?RT. 

For G&ssscdore §4 compucsrs using interfaces such as the CARDCO, you may have 
to ssiect some special mode before sending escape sequences to your printer. 
For example, the CARDCO model G+ needs to be opened with C64PSA=5 and C64PUL=0 

(as described above) in order tc select "transparent mode"* 

OUTPUT TO SCRBEI AID PRINTER 

Sometimes you may want to output the ssse text to the screen and the 
printer. This can be accomplished by executing the same PUTF or OUTPUTF 

statement twice, using different file handles « for example, the following 
program fragment supports selective output tc either just the screen or to the 
screen and printer; 

WORD 5? [2] : File handles for screen, printer 

WORD 30TH0U7 ; =0 if just screen. 1 if screen + printer output wanted 
WORD 1 

SP[C]=STD0UT ; screen file handle (already open) 
B0TH0UT=0 

PUT NL , " Do you wish output to printer too?" 
IF TOUPPER(GETC)='Y' ; yes? 

SP[l]=0PEN( ,e P'V\O 5 then open printer for writing 

B0TH0UT=1 
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. go to printer & screen 



ARGUMENT FASSil€ F] E EXECUTIVE 



PROMAL provides a simple li.rir: zcz raj-Ini z:'izzzziZ~-\zii~ ziz^zvlIi- :c,i 
Li~~. " TITTLE to a program. T;^ -f": — ,* "^Z" r'<\ r -"~ff ~ - r r - c~ 
ii"- -v : -r-- -'lies which are pre'-.-: v I3!"T7T . v ' _ . ■ , . ^ . i is ras-i-l j: a 



the number ri arguments passed to the program. 

a string zz ; coining tra lira: * gument , if present 

£ string containing the second argument;, if present 



3 AEG g" iaC-ARG ] 

CAM? J© J 



is the last argument. 

is a string containing the command which was executed (the 
command name) 



jqz szEtrpia. if ;-cur program is executed Zj tha EXECl T Tl T /3 command; 



DOIT Myfile 2367 



then on entry to the program, 

NCARG will be 2 

CARG[1] will be "MYFILE 

CARG[2] - will be "2367" 

C aRG [ G ] will be 9S D01T ,e 



All the CARG array elements will be pointers to strings containing the argu- 
ments o The program should consider these strings as DATA and not modify them 
in place. 

The EXECUTIVE normally treats blanks as the delimiters between arguments. 
Both leading and trailing blanks are stripped off the arguments, so any number 
of blanks may intervene between arguments. Also, the EXECUTIVE "folds" all 
lower case letters cc upper case. However, if an argument is enclosed in 
quotes on the command line ? then the entire quoted scring is passed as a single 
argument , including blanks (if any) 5 without folding alphabetic characters . The 
quotes themselves are stripped off. For example 9 if the command line was; 



FIND "Now is the time for all good men 



then; NCARG will be 1 

CARG[I] will be "Now is the time for all good men' 9 

Command line arguments from the EXECUTIVE make a very useful way to pass 
file names or numeric values to a program* For example, here is a program 
segment which opens an input file specified on the command line for reading; 
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PRC "Z r " Z?" 




7^ 



ABORT ^":,r: i- -RIZZZ, expect-; 1 ^:;.:-.:.n ^rliiih 1^ : i name." 
INFILE « IZZZi -\Z^ L Z] , 
IF INFILj - . "'^^ ---ror? 

PUT ML, 9t *** Error; " 

CHOOSE IOERROR ; error code from 3 JIN 
2 

PUT C...lC:i ~ - " is i3t a legal filr name." 

3 

PUT ~r^~- r- 1 ready. 9 ' 

4 

PUT CARG f 1 } s 8 file net fcundo" 
ELSE ; _ aust.c.l Brrrr ; ~ o:: ~ >:nd 

PUT " Car,' z z pen 58 f CARG « I ~ 
ABORT 

WHILE GETLF (INFILE, LINE) ; read lines _;tll ««d gi file 

Of course, you could make the error processing simpler if you wished, or 
make it more sophisticated (perhaps by giving the user a chance to try another 
file name) j as is appropriate to the application. 

SSxSSS&L W41IA1L1S FOR ADDRESS ISPS SPECIAL USSKJ&Y L3SJLl!i0tS 

In BASIC you use PEEK end POKE to examine or sec special memory locations in 

-.-cur cor^rter. T -;ith ¥?j7£kZ : ycc csn -rit^ the eqr:: ! ~ 7 £len*~ PEEK" er-d POSE as 
follows i 

BASIC PROMAL 

X=PEEK( Tinnn) X=M [ rmnnj 

POKE nnnn,X M[nnnn]=X 

where nnnn is the address of interest • The array If is predefined in the 
LIBRARY to be an array of bytes encompassing all memory., so M [ ] is the first 
byte of memory £ and MT 65535] is ths last byte of seicrjc 

However, there is an even better way to replace those PEEKS and POKES which 
is both more readable and more efficient. You can give those special memory 
locations a variable name of cype BYTE, by declaring them to be ZXler^a! zc 
your program. For example for the Apple lis 

EXT BYTE HIRESON AT $C057 

defines a variable named HIRESON of type BYTE which will be assigned the 

address $CQ57 e This is the Apple "soft switch 9 * for enabling graphics mode. 
Once defined, you can enable hi-res mode by merely saying, 



HIRESON=TRUE 




rROi v jAL , you zz~. gi^s "h^se registers a variable name and manipulate them just 
like any -th-f -triable. This kind of variable is called an EXTERNAL variable 
because it re located outsi :h the PROMAL program. 



For exat,!;, t",j BASIC statement, 



POKE 531/ 1." 



sets the screen background color to yellow. With PROMAL, you might choose to 
do the equivalent function 1 1 he this : 

COM YELLOW - 7 

EXT BYTE BACKGROUND AT 53281 ; Screen Background color reg- 
BACKGROUND = YELLOW 



Ones have defined tie address tf the variable BACKGROUND, you can use 
tz jus : _ ly other PRO LYL - z^iai--, 



Crs? ":.:.g valuation with sprites is uuch easier with Fh^MAL. Per example, 
suppose jou. wanted to have a caak moving horizontally or. the screen €.s one 
sprite and a bomb falling vertical 1" T *s a second sprite- Ten mighr or this as 
s : 



EXT BYTE XCAR AT $D000 £ ^.iiticn of s;:;i': = 

EXT BYTE YCAR AT $D001 ;\ resreior sy-iro " 

EXT BYTE XBOMB AT $0002 ~h ccsitrcn cr dcig 

EXT BYTE YBOMB AT $0003 ;Y ccsiti cn of laffib 

XCA1 = XCAR ~ CARSPPEED ;move car to righc 

YBOMB = YBGliB -r BOMB SPEED ;move bomb dot-- is dew) 



iri this case the address cf each external variable was specified in 
hexadecimal, which is frequently eorc convenient . 

You can also directly maniyrl^rce screen memory or color memory as a PROMAL 

array. For example, suppose you vented to clear the standard screen, and then 
"paint" 16 bars across the screen, each ir a different color; 
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; fill the screen with blames 

I one :* i„ : I r averse-video blanks 
; £r-7 corresponding co 1 _i .2 

I"' :.i ,e tl>. ; ^i- ex'~^j^l ~ ;-v eclaration does not specify the sirs cf 

array inside the bract et~ J "J ^ :e because PROMAL does not need to reserve any 

space within the progr-r* - rray (and because PROMAL does not do any 
bounds-checking on arr«y - 3.f ~':sr because this would adverse!" affect 

exec*~ ' 1 - c ~;eed' 7h-. - c~ ■: = ?1LL is a built-in LIBRARY subroutine which 

fills a portion cf verier y -ji'h a specified byte. its first argument Is zhe 
starting address. t:i£ -„• ..o: :tf :\: number of byte^ ': fill, and the last 

argument is the 1 : i-1 character. 

Just for let's compare the above program segment to its equivalent 

BASIC program; 

90 SC-lGlU 52=1000: tl-lf2?t 
100 FOR I-SC TO SC+S2 ; ?CI1E 1,32? NEXT 
111 FOE 1=0 TO 15 

ilG 3 OR 0-^0*1 TO 40' 1- - : IZ-i : IzOi 1EXT 

lzC FOR J=40*I TO 40" 1-3;: FIFL CC~J. Ir NEXT 

140 K'EXT 1 

If you run the BASIC program and the PROMAL program above, and time how 
long each takes to clear and paint the screen, you will finds 

Utile z „ c < s::u; 11 seconds. 
PElIl-1 . .-fl^c: f 1 seconds • 

This is arxtnar reason why PROMAL is much better than BASIC for animated 
graphics FF.CM-1 Is much faster. While : o~ 7 ery PROMAL program will be 140 

times faster than its BASIC counterpart as i ;: this example, speed increases of 
20 to ICC tisss :r sere are commonplace. Also, the larger and more complex the 
program, the greater will be the relative speed improvement compared with 
BASIC « Using the built-in LIBRARY subroutines wherever possible will speed up 
your PROMAL programs even more, as well as making them smaller and easier to 
debug. 

Several PROMAL demonstration programs making extensive use r 1 -.he graphics 
and sound capabilities of the Commodore 64 can be found on the l:~modcre disk. 
You can learr. a lot about PROMAL from studying these samples and improv- 
ing tnera or changing them to sure your own taste. 
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~~ r"v d~ ■ ;.b£-I -i: l. .i^r.ln:. . routine, PROMAL makes 

_t t: r ~- tn-n "J ; IL^iL c_ ~ ri- si £, si-^n interface to machine 

lsrfgw$ga : tct'i f^r ^> -riiti; j:-^ -r„ics ^nc . i Hi „ sd i:-.^at routines in your 

computers operating system* You can call any machine language routine ir, 
without writing any machine language interface code at all. You can call, 
machine language routines by name , with passed arguments, just like regular 
PROMAL routines . You can even specify the contents cf irs hardware registers 
and test tl,e results when the machine language routines return (incl*:- : i~5 tre 
flags). You can embed machine language routines inside PROMAL programs using 
DATA statements or load then, from separate files under program control You 
can also call all the built-in PROMAL LIBRARY routines from your machine 
language routines . 

Appendix 1 describes how to use and rriee machine language routines, with 
examples . 
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SHUBCS 



:.;.H2c:ir -.f ^t.::g t This is "srj :c r7aii-:: ; sines Lsfariing — £:.:. sil^? 

nans anrciracL^a^Iy gst^rctei a reterane- _ z> :Lr ^i^^e c_ ^ - : ::*"-st alarant - 

For example: 

WORD I 

BYTE BU' " ' f " put line string 

GETL BIT ; Input line :roi keyboard as string 

I>3UF ; I points to string 

Assuming that this program was executed ana rkat the user entered "Hello" 
from the keyboard, che memory for the variables night look like this, assuming 
some arbitrary addresses for the variables s'ciuwn in hex): 



5B04 ; 5B4^ j Variable I p cirrs rc 3uF 

. 1 34 



5B44 <Z i c5 , S3 \ SC : 55 X * ; zn j nx \ Variable BUF = "Hello 



The °nn/ q in the diagram above risans 'den"":: care" or "undefined" . 

A big advantage ~f cri? representation of a string is thee ncu can use the 

same array to either refer zo the whole string, or to access single characters 
from the string. For axa-rpies 

PUT BUF 

will display "Hello ,E : because the PUT procedure is passed the address of the 
string {$5B44 in the diagram above) . Anytime you write the name of an array 
without any subscripts, the compiler uses the starting address of the array. 
You could extract a single character from BUF because it is an array of bytes. 
For examples 

PUT BUF [ 1 ] 
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from 
can 



WORD 1 

BYTE BUF [81] 

GETL BUF 

I-3UF 

PUT I 

would cause whatevc:. line was typed to be printed out . However 5 if urease 
statements were followed by: 

MOVSTR "Gone.", BUF 
PUT 1 

then "Gone." would be printed, because I contains the address : f BUF. 

Similarly, you can't compare two strings with the ordinary comparison 
operators • For ezample : 

DATA WORD BIT i - "Hello" 
DATA WORD BUF "I - "Hello" 

IF BUF1 = BUF 2 ; Wrc" -h 

PUT "Strings are the same" 

will never prin: a:..; thing because the string given by BUF I ^ill raver ha T ~ chs 

aairc address as ::he string given by BUF 2, even chough the contends of : ;.ie 

strings are the sense This should be written as: 

IF CMPST1 ( BUF 1 r * = BUF 2 ; 

PUT "Strings are the same" 

ADDRESS Of AN AEZhh FhUffilT VERSUS CONTENT CF liS^'I ZLHU21T 

It is very important to understand "ha difference 3et"esc the address of an 
array and the value of an element ir_ rr array = "Remember that almost all the 
buil t-ir library functir:.? and procedures frr ^rrirg handling expect the 

address cf "he string fcr an argumerrr ."if the description zf zee routine says 

it experts a string, this means the redress cf che sering; , If you pass a 
single character where a string address is expected, you might create big 
problems! Here's an examples 
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BYTE . 

C . ; This is wrong! 

PUT ML, BOP 

Here the programme', siu^ 1 - T - - : ~- r r-: : i;_~ f.::a th^ : — 

the array BUF starrtn,:: a: -« : i"ET -i-i-r-- ^ - r::^^. ^ :y — * * i s 

to work, but alway: ~;^t rortr^:: £i lUftii^ I . rls 

c ompu ter . Why ? 

The r; :. ■: It'c : ? a that GETL expects the addr^^? :f ;ic buf f e~ tc receive the 
inpu" , br t the expression BUFT^ evaluates as ihe od^ra of tee --oa:. ?r.r=r 

of the buffer* In other words, whatever character is in BUF [ i ■ ?/ner ihe call 
is made (soine g£rbag~ "■€ Ice rec-'se:.. 1 and 255' ; is passed to the GETL renins as 
the address? ~ : -- 5£ are } o- *ra- - -re i"ut Una gc c 13 XL obliges by z^z-Lz^ 
the input line iF-^neplaoe i~ the first 256 b; 7 tes of ne^ory - but met in the BUF 
array. Whan 57? is ~*c: cizec V~ rra ?"JT statement ic shows garbage- hacanse it 
had never been set : Because the first 256 bytes cf memory is "zero page' c and 
holds eri;tsal cperelirg sysie: - ?Z r *¥AZ i -~s.zi.~~ , overwriting it 
cause the co^Lts: to craeh^ nsr e^-sl te ting ^ ~e-lcc t - 

How do you f i„. .his? In this case, the easiest i^v is -inoly jr '-rites 

GETL BUF 

without the subscript, since PROMAL will always use the address of the array if 
you write its name without subscripts. 

But what if you don't want the line to go right at the beginning of the 
array? Suppose, for example., you have a two dimensional array such as: 

BYTE SCRN 7 it- ; n- iires of 80 characters each 

low suppose yoa -fiezic co input a line from the keyboaro :-.a'zo the ttir i cf 
the array c Sere is how you do this t 

GETL #SCRu 2; ; lead line from keyboard to 3rd row 

Toe & operator tells the compiler to generate the address of the specified 
array element rather than the value of that element o The third element 
subscribe is 2 inscead of 3 because the first eiemenr. is always 3 ? not 1 . 
Moie importantly :: remember chat the last element is 24- not 25 * If you try to 
read in the 15rh line using; 

GETL f'/SCRH [ r 25], 30 ; Wrong! Out of bounds! 

GETL will oblige you by reading the line into memory over whatever happens to 
be in memory after the end of the SCR1 array! This will have unpredictable and 
invariably unpleasant results a 
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; - string which starts <r 2 : nation 5: :r: 

£io byte) . The following statement * - ~zt 



This state : - 1" 1111:1 t\. "_y 1" r fi^n char=iin if Lh~ ili^i- f icause the 

expression -i.il s -gujace tc che -srr.e of :ie rirs :. byte of ras array X (which 
is assumed li ha ai. /.ECU crars^iar ^i^a) . 7~JI is oae cf Hie f ai~ ri^tir-es, 
that can accept a single ifii&racicr ;^ a spring* If the argrraern is ^sss J nan 
256, PUT assise? fsis sreir^sn; is € singl™ .i3C7 1 nans itar arf ~rir"-~ ~_ '- .. z £ 
" - ii argume: : ;i insi^r iha:: J3c. assies z'z.e orguirer. t is crie Morass :f i 

el' 1 ng to -i i'-: nee- 

SEQUENCE 01' ^fLii/- OIMENS IXI^ff ^32±Z IllffflZTE 

When using tnul t i -d imens i o -:a 1 arrays, :xc& 1 lit c iha array elements with the 
first g^bocript ~rill be adjaeeril in. i£6uk>iy ? &o vo^, should have the column 
subs.it ipt first and the row subscript second- For example : 

fill f.h.GE ~ ~ : 25 ~ ? r.i iz. for ^5 fir. as if S ciars each 

i wi, _ n.cL: U . 1 I r ClsCc" tl!l^-i»S l^oldvfeSr O 1 G ." r j. Z l — _ „*ltb, . - ""'X 

?ji ^rASE^JCrf] ? fisrlar srtirs siring rf 6:1 : 'r-~ 



fn His raga ir:ei ara allocated lifa if is ic xeicif c 



J 



axcthsr way tc lock at ihls is tc say that an array declared as; 

WORD stuff ;io : so: 

declares 50 groups cf 10 fiords each, not 10 groups of 50 words each* This 
distinction becomes inportai:: if you use BLKM0V to move part of the array or 
FILL to clear part cf the array • 
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as an argument* 



Here is a progrc.^. f :c.giL5:: ?~~c r -:z z V~~ develop an ar:;\: / _-f 5 : ' 

reading them from the keyboard or ~ riie. Tv*put is terminated ~n aic 
(CTRL-Z from the keyboard)* 



WORD STRIN :-:!->;] ; Arr*- ~T =;:v;.2f ^ir_c«r* d:,i> VjF arra<- 

BYTE BUF[£100> " ; Stor^e f-r urV~ ICO ?--rir2« ?.f 40 char enr/r 
WORD 1 

WORD NSTRING ; Actual Timber of scrf.ngs r not exceeding 100, 

NSTRING=0 
I=BUF 

WHILE GETLF(STDIN ; I. 42; s - Bead s^rdng to address 1 

STRING [NSTRING] -I - Install pointer in string array 

1-1441 1 Starting addr of next string 

NSTRING=NSTRING+1 



At the end of this program fragment, memory might look li':.c -J:jL - assuming 
the lines read were "7i:~s:", "Second 5 * , etc. 



d?F9 : STRilfd 



. " "0 



5FF9 



soo[ 



The Id STRING demo program uses a similar technique, but makes more 
effici-^c use of the BUF array. You may wish to use the sorting routine 
provir d ir SORT STRING for your own programs. 
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- jORAL VARIABLES TO ZERO 




decl^jri like this J 
WCV- ^"RSTVAR 

bite ^st^j? n ; 

where FiRSTT^B Is the first variable you want to zero and LASTVAR is a dummy 

variable you sec after the last variable declared * At the start of your 
program, ucs^ 

TILL ^riZ2r7AF ? * IAS T Vjl?. ? J ZRS'~ l ~>-JL , C ; Is: o all variables 

This -lil set all, tie variables f^r^r ?I??T ff 'A.r rp to (~r- rot inclrr ir:^ lAS^A^l 
tc sErc- jcr:"t fcrget ths 15 operatcrel Als:^ cote the z d^STVAR i? e^i array- 
Tb id is recsssary in the Ccaacdors and Apple versions cf PROMAL because tfcs 
PRCil^l. _ ^r^il^er segregates scsil^r sad array variables ll Esalaas sder esses 
fcr all t '.'is scalar variables first {in tae order declared"* : and thet? ^11 the 
arrays \±»z zhe order declared) <> DATA variables are par; of 'che code area of 
yoar program, not part of the <i&la. D so you don^t have to v'orry about 
accidents lly zeroing the value of DATA identifiers. 
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These capabilici-3 are provided by the bull: i-_ :i>rary procedure 
which is used to control the loading, execution, and disposition of compiled 
programs and overlays . This procedure is extremely powerful, much more 
powerful than the simple "chaining" capability provided by BASIC and some other 
languages. To use it effectively requires an understanding of the loading and 
execution process as used by PROMAL , p] - new terminology. The remainder 

of this section deals with the LOADer. You zaj wish tc s\ip over this section 
until you are familiar enough with PROKA" *~ . "; - writinp : ^ge programs . 

DEFICIT™*!? 

Tie icl-..:/:?!--^. v:i:.r.s are relevant to this sectic ^ The meaning of 

these terras Till become clearer as the discussion develops , 

&. Module is zna object file produced by the PEGkAL CCKPILS7 (wiLn ^rror 
messages ' ; ^ith a «G extension, or a relocatacle machine language Drogrem as 

generated cp i/na RELOCATE program (discussed t: ^p^-zir, 1^ 

Am Entry Point is tha place where execution bag Ins in a r eerie Ir a ?3JMAL 

source program- the entry point is representee I>y B3ilP s^ia^a^t mellowing 
the las*- p^r^e-lrr^ or f unr ci on in the source program. 

1- Lsgissl ?rcgir£z: ie & collection of one or more modules whi i : zslten 
together ; comprise a logically complete program for some purpose* A logical 

program rsay have several modules, each residing on disk ir, £. separate lil~- As 
a ^iriaum, a logical program has one module. 

J ?rcgrgs: is a compiled PROK^l program. Normally it performs a complete 
task by itself and is composed cf an arbitrary number of procedures and 
functions, with exactly one entry point, which is at tha BEGIN statement 
following the last procedure or function. The program source file begins with 
a PROGRAM statement, is compiled from one or more source files, and the 
resulting output module is contained in a single objec : fil= v*i :^ a - C 
extension. 
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Loading: \..z -. ; :ocet ~ :i :jl:i;" r a PROMAL module from disk and cop": - ~ " 
into memo::;-' rrking any &u jus emeu cs (called relocations) to the program 
which are ::.~ci.~d to correct address ~i :Lr ;:a program, or interface cr c:-ier 
modules , etc transferring control of execution to the program, if desired . 

Chaining is >; special kind of loading rhera Vre program being loaded 
replaces the program which called the loader c 

WM^KZHG L LOGICAL PROGRAM INTO MODULES 

L'bars j. j a severe! reasons v; - h" jr~ elg'h:.; ;•: r~ - s a logical program 

composed ::f several modules instep cf a 3ingls^ ^cr.cl:l : :hic program: 

1 . The program is too large r: : r ii.eii.or 7 at crxe . 

2. The program is composed of logically separate modules (for instance, an 
accounting system might have a main menu with separate modules for receivables , 
payables , order processing, report generation, etc) . 

3. The program uses a logically-related group of subroutines which are not 
frequently changed and therefore do not need to be re-compiled (for example, 
the PROMAL graphics package or real functions) . 

4. The program takes too long to compile in its entirety. 

5. The program uses large machine language routines (this is discussed in 

rippeacix I) » 

The PROMAL LOADer is a built-ii procedure in the Library, called the same 
way as other library routines * You have already seen the PROMAL loader 
wo rking, at least indirectly - v 7 hen you type the name of a program you want 
executed from the EXECUTIVE, zne EXECUTIVE calls the LOAD procedure to run your 
program. When your program finishes . it returns rhrcegh the LOADer to the 
EXECUTIVE at the point from ;-:nich it v&s called* 

Your programs car. in trrn load and run. other programs or overlays r by- 
specifying the name cf cha program to run, and optionally some flags indicating 
hc~t7 the program should be run . Briefly, the LOADer performs these tasks; 

lo Looks to see if the specified program or overlay is already in memory, 

and if so s executes it beginning at the entry point • Otherwise, it; 
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nierrory z^zz: 




Z.Z. 4 IZ S Z Z, v '•" 'Z Z z c. C 1 if 6 T S "' Z 3 5 ~ Z r Z'z r C'i'J,lr,» 3 " ; ~f ~. - ^Z^ '. ~- " * ~ f ^ H 

1 1 o , _ 1 o os a z : _ a, s i: ^ - 



5s The loader than begins execution c-i y : :z pi r ' r-c^ :: ;h~ antry point . 

60 When your crcgram completes \by ccr:.„ug Ee 7 I cce main program, 

calling ELIT z'z ABC57, or encountering a ^iLii"- rrr.v ^ - th~ leader temporarily 
regains central. It noma^ly transfers czuz^zl, ~ ^ r x ^ tie = i cgram which 
call c ^" ";-> - r. : the statement f elIe T '~~ r -I^ -r t 1- leader. However, 

if yovr cr. - gram called ABORT or encountered a runtime error, control is passed 
direct!;- back to the EXECUTIVE instead. 

Toe pxog- am which calls tie LOADer : execute another program is called the 
parent of chat program. Tiie new program :3 called the offspring of the program 

that called the loader . The loader keaos Oracle of the modules currently In 
memory by a series of tables * These tables have room enough for up to six 
modules to be resident in memory at once, plus the EXECUTIVE and EDITOR. These 
modules may be ail part of one logical progr z ympletely separate programs, 
or any combination • 

The IG^I^r eiso uses several pointers for memory managericl Hie most 
important rf theses are called LOFREE and HIFREE • LOFREZ always points to the 

first byte zz unused memory, and HIFREE always j^l^ts tc the cyle aftar the 
last jn^Scd uj ca of memory. These pointers always poinr zc z z:sgz hcandary In 
mexory (thai ls ; the address Is of die form $XX1C ; . Normally ere ICADer 

allocates programs f ror the bottom of available memory u:. ; anl variables from 
the top down. No rmally variables from one module can occupy the same memory as 
variables for another program since the variables have no Initial value and the 
programs are not related. However, the key word OWN on the PROGRAM or an 
OVERLAY declaration of a program can be usee to force the loader to allocate 
the variables immediately after the program, not shared with any other 
programs. OVERLAYS always have their varim: las allocated immediately after the 
overlay code. 

The following nasorj diagram shows a series of programs being loaded from 
the EXECUTIVE % 
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H1FEEE -> 



E " t - 7-—- ' ~ -= - '7^2 

o ■ ?;^i 

R LOFREE - - 

Y 

~- '.v -A , ??v'-?^. r 

LOFREE 

;a; (b) c; id} 

Tine —> 

Time is represented on the horizontal axis and memory on the ~er ileal arris, 
with the h trrsf, : addresses s l tie top* The diagram jar resents t~a ^c~Lj 
configuration for the Apple. The Commodore 64 conf igurarlor. i? so t rer;c$ - -ore 
complicated (see Appendix G) , because the Workspace is also managed 1 y the 
LOADer, but the principle is the same- In this diagram there are initially no 
programs in memory ( except rhe EXECUTIVE/EDITOR, net s >io\vr.) • Then r^u^A is 
executed (part b of the figure), which is a normal module. P1GB is men 
executed. PRGZ hat y> r :~ its rrcgrar; lire, sc its variables are c 11: calel 
after the code for ?ZG3 irsteaf or sharing ics variable space with PRGAr 
Finailjc P1GC is r:m. "-"hich is another rornal program, and shares its variable 
space with PRG^„ Sirr.e laq^iras acre variable space than PEG A, HIFREE is 

lowered by the leads/ . £I5REE r~ili alrays pclrt r- the start of the variables 
for whatever ia^ict^ ..ewlrrei? res largesc hiccx of shared variable space. 

In this example , all the programs were small enough zz fie ir memory at 
otcee If P1GC had been too large to fit, the leader would first unload PRGB 
and its variables and try again. If there wa e still not enough roo»i s it would 
unload PRGA. When a program is unloaded, the ICADer simply deletes its table 
entry ^nc moves the LOFREE pointer down (and the HIFREE pointer up, if 
possible); to recover the space. It does not clear the memory recovered- 

Her m zmjl the mMm, 

The declarations needed to access the LOADer are in a file called PROSYS.S 
on the PROMAL system disk. Therefore you should have i 

INCLUDE PROSYS 

near the top of any crcgrar: which will re calling the loader (or : if you wish, 
you can extract the definitions from PRGSYS and insert them directly into your 
program with the EBlTcr^c 
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1 1.1; rrr.:r ^ nodule was successfully leaded/ executed * 

1 Module was tier ~ound in memory or or* Jxsl: 1: z:,e na^a Is 

illegal) 

2 Not a ~eL±l H.1L1-JL, model .*^g°^ -rot a successfully compiled 
program; ^ 

3 lot encrgl. Iras nemory t ~ lead program. 

4 Module required cot loaded or relocation err ri K ^ogc : ,;le 
module to be loaded calls a subroutine in £-cr .rer - <r 
which is not loaded' , 



For example, 



PROGRAM MYPROG 
INCLUDE LIBRARY 
INCLUDE PROSYS 

BEGIN 

a ♦ • 

LOAD "YOURPROG" 

IF LDERR <> 

ABORT "#C Unable to load YOURPROG" 

E1D 



will cause the module YOURPROG, C to be leaded into me^cr; % tf it r* net already 
there) and executed* After YOURPROG ends, control will rctrrn zc the I? 

statement following the call, which tests for a loader error (si* eh as file net 
found). If s however, YOURPROG called ABORT or encountered a runciae Error, 

control would never return to the IF statement above, but would return directly 
to the EXECUTIVE instead. 



LOADER OPTIONS USING 111 FLAGS 



The second, optional argument of type BYTE can be used tc specify a variety 
of options which control the loading process . This byte is treated by the 
LOADer as several one-bit TRUE/FALSE flags. These flags are given names in 
PROSYS, defined as follows; 
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. ... 



LDPRCLR 



$02 



:~ rnninaru avaiia:: a memory for a 



LDRE 



$04 



if mi 



tCS arrcl^lif 



le 



is in asiaer^c If FALSE IK ft "-III net la reloaded 



eao^ iXE-ieo cr 



ne^cry-resldenc copy nas oesn ccirrncedo ifcte that 
specifying LDCHAIN-I cr liI^IF-l ^: t—V.-c 
LDRE LI-"' automatically. 



LD1ECLM $08 lert^in i^ory on exit- If TRUE 2 tier cr^ ■ 

specified nodule should be unloaded from memory 
after It completes execution. This option Is normally 
nsed for overlays to make rocr far ether overlays 
in the rc^e memory space. If C r ere module will 
remain loaded on completion and can be re-executed 
ry c - rl ^ac rent If LI rltri-i having to access the disk. 

LDN0G0 $10 Ic act czecctac If HUE {i; , then j.ha specified 

rolul ~- -ell le ^caoec In re ratio ry 11 ? :c Ic zee 
sL" a es dy 1 ~ - 1 .-. I " -vf - 1 r t -xn cr t f r g 1 -~ I % : c ^rrtron 
is normally used to insure trat a icclis Is leafed 
and ready for later execution-. It is also used to 
control the sequence of loading of multiple modules 
In a complex logical program. If C r the specified 
iiiCccls vlll he executed . 



LDUNLD $20 Unload. If 13111(1;, then the specified module is 

unleaded Instead cf leaded- No other action takes 
place and all other hit flags are Ignored. Note 
heat any program leaded aho^a the specified module 
will also be unloaded. If the calling module is itself 
unloaded as a result of this process, control will 
return to the parent program Instead. This option 
Is normally used to free up additional memory • 



The hit f la & s above can be combined in any sensible combination. For 
example j 



LOAD "HISPROG", LDCHAIN + LDRECLM 
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--'-ill -^vl ^11 ^27-;-i>^z t -_r--.:- y, load NEXTCOMD without executing it, and 
-* \ cl - &.T71 : 11~ 7 U. vou might want to do this to setup the next 

Tl:i:i :^r:iL^i2\ 711:111:121 -.ic iiiiii;i:ii :::: szszk modules 

0"~ - t>a iic^. - _-werf ul feature? c :5 rhe PROMAL LCl^-ir !*■ that when a module 
is loaded and executed i .. - 1 Cc " ".. -elected procedures and functions and 
access ^elects' 3 , "triable?: ic c ;her modules which are already loadgjU it 
canoe c , lwe r ^^ reference procedures, functions - or icbles in modules which 
ha-re cc t rear.. tc^le- yst . This is a logical extension or die ru„e t^t 
J ._i_Cr : pjoo^d^as and variables must be defined before they are 
:8feraicsa 6 it is up to you, the programmer, to determine which procedures, 
- — ... - - - ^ cbles will be made available to other modules* This la done 

ii.v?:~l* i iiorts . 

In a PROMAL source program, the 1. ~ / "cr: H:i?Grii c&.~ 1 s use J. 1 ■", 1 _ :at of any 
decler^cicc cc a cccs^aat, data declsrsci*~r. .> 7sriEbIe s procedure > or function" 
to designaca c^<- its'b ^cich should be ;ic£de avails.:. Is tc ether -cede- vhich wish 
to use it c If yc^r crcgram contains amy EXPORT^ „ : z^st also have the 
keyweix Illim ^ : ~ ~ 1 10 GRAM (or 0V112-1:) lin- " T "^ T -hc:ld also be specified- 

Fvr :iirp^s~s f i^iiscrc:!.:^ 1st tts^s " v 5 rill -'.^-""e a logics! program 

compobtc .1 _:;c 3 e F £.a;a ii.cJ< Ce 1:: fir c . _ la c, collection of 

subroutines which you frequently use. c-llal 1 J3r l.G ; che other module is a 

parti application program calie. : hll^ll fhlcl ?ill , se some routines in 

SUBPKG larl in addition has some proccct^rc- l^zizz^c a^d global variables of 
its ciiri ; . Assume you wish to compile the subroutine package and MYP10G 
sepals cei} r : because SUBPKG is already well-c-V-gged and is fairly large. 
Thereic during development of MYPROG yes -nil not have to re-compile SUBPKG 
each ti^se yea make a change to MYPROG 5sr-i^ 'ci^e* Here is a skeletal viexf of 
the source for SUBPKG: 

PROGRAM SUBPKG OWN EXPORT 
INCLUDE LIBRARY 

WORD I 

EXPORT WORD CLEARANCE 
EXPORT COM WORD P00LSIZE=500 

EXPORT REAL POOL [POOLS iZE ] 
REAL THRESHOLD 

EXPORT DATA REAL 71 = 3. 1413? 26535 

EXPORT DATA WORD ERRMSGS [] = 

"Pool exhausted", "Undefined pool element", "Illegal pool element 8 * ,0 
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END 



FU1C REAL BESTGUESS 

» • • 

BID 

EXPORT FU1C BYTE CHECKERROR 

END 

• # • 

BEGIN 
BID 

This example illustrates how a subroutine package might make selected 
identifiers available; tr-i use by other, separately compiled modules* In this 
case : cbe names CLEARANCE , POOLSIZE, POOL, PI, ERRMSGS , ADDTOPOOL, and 
CHECKERROR will be exported- The ..?...ir? I, THRESHOLD, and BESTGUESS will n.j: - - 
available for use by other modules , In. : ;aer words , the subroutine BESTGUESS 
can be called by other routines : :.. n; lule (PROGRAM SUBPKG ; ; tut not by 

other separately compiled modulse * 

When a program contains EXPORTS , the PROMAL COMPILER writes the definitions 
zf all the exported items to a special text, file ^ rha completion of 
compilation. This text file will have the same name as is on the PROGRAM 
declaration In tea source fila s but with a .1 extension. For example, the 
program above would cause the compiler to generate an export file called 
SDBPKG.E, which might loci- like this: 

IMPORT SUBPKG - 11 '17/S5 

EXT FUNC BYTE GBElsZiOll AT $0562 

EXT PROC ADDTCPCCL AT |3250 

EXT DATA WORD ERRMSGS -4] .%! $000D 

EXT DATA REAL ?I AT $0007 

EXT REAL POOL [500] AT $0000+$4 

CON WORD POOLSIZE = $01F4 

EXT WORD CLEARANCE AT $0002 

This Ills cells the dsfi^itio-ns cf the exported identifiers, relative to the 
start of the SUBPKG taodnlsc It 1? not necessary to understand the exact 
meaning cf ths Individual lines » The top line tells the name of the exporting 
program and the compilation date. 

PORTING DEFINITIONS 

Once the export file has been written by the COMPILER, you may INCLUDE it in 
the compilation of another, separate module, to import all the desired 
definitions . For example, another separately-compiled program which uses the 
SUBPKG module might look like this: 
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END 



BEGIN 

IS ,t > rOOLSIZE 

put lnl/errmsg:, : ^ 

END 

Notics z\sz zc±s program uses the procedure ADDTOPOOL, the data items PI and 
ERRMSGS, and the constant POOLSIZE without ever explicitly declaring them. 
This is possible because cV.s INCLUDE SUBPKG.E will cause the definitions to be 
imported o Please neta thst yju must specify the .1 extension on the INCLUDE 
statement | otherwise, the compiler will look for the file SUBPKG. S instead by 
default. 

13S^7J1I3C sFM LOGICAL PRC S^ll ZZTH Slf£2£S2 "ICZUZlz 

after compiling MYPROG, yon will ha-e t"G senary :s modules which work 
togeta^Tt SUBPKG. C and MYPROG. C. If yc. ^zz-zzzz zz - ^cute MYPROG. C from the 
EXECUTIVE, you will get the message: 

NOT LOADED OR RELOC ERROR: SUBPKG 

This is eecause the SUBPKG module meet be loaded before the MYPROG module which 
calls 11, Etid you haven't loaded it. To solve this problem, you could type; 

UNLOAD 
GET SUBPKG 
MYPROG 

which wouli ^rilosd any existing programs v zc ~zaka sure there's enough room for 
both modules"; Iced the SUBPKG module, az,c then load and execuce the MYPROG 
module. The LC-'Csr is able to relocate all the references to routines in 
SUBPKG corrsi :ly because '1 v it -vvo-rs -jhara it leaded SUBPKG into memory, and 
■ Z) it knovs ;„> 5 dsf initions cf tha references to the exported i:«=:~is in SUBPKG 
as a Jcsul; cf chs compilation ,: f >Z?^CG.. 
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Lch need to be 
program, whose jrf 
then run the main 

LI a ;1 5.7 J a & v I** f ~ - --If 1- r:ur a- a r-~yu --i voices) 

- ~i *?o : t: :is frcrrer^ r^rr -re .t€~r osn i~~r I ~-?>.±I s :(ir res; :f the program 
is loa ' "L _ i disk. 

2, \ v.. v modules needer i~ ... desired order, using the LD10G0 option 

on each ^w-I ...all to prevent c. :s i, 

3 • Load and execute the main module. 

In some cases, you may even want to use a two-stage boots : rr 1 :r i rroro 
i: el firs; ?--^gs bootstrap loader signs on and then LOADs the se^,: od ro -^;rcc 
r "oge loader wir- the LDPRCLR option to Insure all possible rrstrorr Is avsilsbls 
lor the application* The second bootstrap then loads all the modules needed cc 
get the program going, In the correct crier to resolve all tL^ uc^c-ide.'icles c 

In some cases you may also use the "bootstrap loader to directly manipulate 
the LOFREE pointer before LOADing some modules I reserve certain areas of 
rex3r}~o 7c r -.k ample, on the Apple II using graphics you may wish to load part 

four logical program below the 8K graphics page from $4000 to $6000, and 
pert above It. Th<- following memory diagram, with program fragment to the 
right, illust-<£.-c3 thl* fc.a; rl^ar examples may be found in the PR0MAL GRAPHICS 
TOOLBOX Mani'i o „ 

If tar programs BOOIfo HYSUBS, and Mf PROG have been compiled fir. to&t order), 
then executing B00II from the executive will cause B00TD to load the 5GB and 
WGS modules, as she™ lo (b; eSccv^, chen sets LOFREE to $6000 under program 
ccotrol r;., reserve the Apple HI -Ear screen area, and finally loads the MYSUBS 
and MYPR0G module to begins execution of MYPR0G. Naturally you should adjust 
to? If FREE pointer only with a good understanding of what you are doing 1 ! 
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P10GMM BootD 
INCLUDE PEOSYS 



LOAD "SGD , %LDIOGO 
LOAD "WGS'^LDIOGO 
LOFREE=$6000 ;end hires 
LOAD "MySubs ,, ,LDNOGO 
OAD "My Prog" 
_ ID 

PROGRAM MySubs OWN EXPORT 



INCLUDE SGD.E 
INCLUDE WGS.E 
EXPORT PROC MyProc 

END 

PROGRAM My Prog 

INCLUDE SGD.E 
INCLUDE WGS.E 
INCLUDE MySubs *E 

MYPROC 

* © • 

END 

1SLP3 

In the previous example £ separate compilation was used primarily es a 
cc^"~ science. Sometimes ,, it is a necessity . This usually happens when a 
logical program is sinply tec large and compls::. t-z fir into the available 
memory space all at once. When this happens , the usual solution is to use 
overlays . it logical program which uses overlays will have one or more modules 
which remain resided; 4 11 Taamoiy throughout execution, and will switch other 
modules in and out of memory c s needed . A typical overlaid program might be 
organized like this : 




This tree diagram indicates that the logical program has a root a©cttjia : 
PROGA, and two mutually-exclusive overlays s OV'LA, and OVLBo By mutually 
exclusive, we mean that only one of the overlays will be in memory at any given 
time. Therefore the overlays can all share the same memory space, so that the 
total space needed will only be equal to the size of the largest overlay, 
instead of the sum of the overlays. 



LOFREE v 



$4C00 - 



I Page 2 I ■ ?£gs 1 l i 




LOFREE -> 



LOMEM -v 



1 

JU- 



GS 



Bcocl \ : Bcctr ; i BootD 



rv, 
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OVERLAY OfLA 




CLLty luOGUico 



TRCGRr*& and ar* C7EELAT. The LOaler will iec aviwO^a. c leal 1;/ mlcac 

to make room for an overlay* If ir old, there would always be possibility 
that the loader would ha- - .: : unload the calling module to maks ro:i for Ire 
overlay. This is contradictory ; : ~ ~ normal use cf overlays , which normally 
retu: ';. , lie parent module when completed. 



PROGRAM FRGC OWN EXPORT 
INCLUDE PROSYS 



iFREI 



LDRECLM 



E LOFREE I 
M 


R 

Y LOMEM 




END 

OVERLAY OfLA OWN 
INCLUDE PRGC.B 
• « • 

END 

PROGRAM OVLB OWN 
INCLUDE PRGC . E 



END 



In our example program 1 j -erlays, the memory diagram might look as 

shown above, with the program skeleton to the right* 

Here that the LDRECLM option was specified or the call to the LIADer • 
This is the normal way to load an overlay which ivlll be replaced hy another 
overlay later. Remember that the LOADer vlll not rnlcsd anything (including 
another overlay) zo make room for an overlay; therefore you will probably want 
tc specify LDRECLM to Insure that the overlay Is unloaded when It Is 
completed* Of course, there is always the possibility that the race module 
might want to call the same overlay agalr. > In this case, you night vant to 
consider leaving the overlay in memory when It completes. If y need ir 
again, the LOADer won't have to actually load ite If you need to replace It 
with a different overlay instead, you can unload It explicitly using the 
LDUNLD option, before loading the desired overlay* 
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in this case, the overlays OVLA, OVLB and OVLC might export variables and 
subroutines to the five overlays at the batten cf zha diagram. Ir. this ease, 
you would need to have the keyword EXPORT on the OVERLAY declaration; 

OVERLAY OVLA EXPOET 

CONSIDERATIONS FOR TEE EXECUTIVE AND EDITOR 

This section tells you how it is possible to load larger programs under 
program control than it is possible to LOAD using the EXECUTIVE GET command, by 
overwriting the space usually reserved for the EDITor . The system pointers 
referred to below are defined ir. PROSYS.S. Further memory map information is 
included in Appendix G. 

As was indicated before, the LOADer always considers the free, allocatable 
space to be between LOFREE and HIFREE • The EXECUTIVE and SLixor bs£h occupy 
the ^sise sddress s^ce y ~?hich is OSORG through MEMLIM (about Llc5X bytes/, but 

only one z£ the :*ther :~hese programs occupies this space at one tics . 

Fcr tne ^ppls 11, z copy of the EDITor and the EXECUTIVE is Kept in the 
extra verier y bahk ? and each is copied back into the normal address space at 
OSORG when needed (this does net apply fcr applications programs generated 
using the GENMASTER program in the Developer's package). Since the EXECUTIVE 
or EDITor are always copied into main memory when needed, all the space, 
including that used by the EXECUTIVE or EDITor, is available fcr allocation for 
your programs by the LOADer ( abeu z 25K) * If you use the GET command to load a 
program which overlaps OSORG ^ hoirever s ic Kill be immediately destroyed when 
the EXECUTIVE is copied back into xemcry vinen the GET command is completed. 
The Workspace for the Apple II ie kept in the excra 64K bank, so it is of no 
concern. 
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<~ MEML1M 
=HIMEM 



MEML1M 



<-- 0S01G 



LOFREE 



<— LOMEM 



HIMEM 
HIFREE 



-> 



OSORG 
WLIM 



/ / nemer 

1 



S 



LOIRE! ™ > 



Memory with no program leaded 



<-~ - LOMEM 



Fr-r rhs Commodore 54^ the titration is somewhat more complicated. The 
Editor is keot in the 12K byna section cf RAM under tL- RClts from $D000 to 
$FFFF whc:- the EXECUTIVE is €;;:-e. When any program is executed, the 
EXECUTIVE is siapped with the EDITOR. The EXECUTIVE Is therefore "hidden" 
under ths BOXs when your programs run, and the EDITOR occupies the space fr:.i 
OSORG zz MEMLIM. When control returns to the EXECUTIVE, it is swapped ^rth the 
ED I Tor again. For the Commodore,, the Workspace is also allocated near the top 
cf '"free memory 98 » 



For large logical programs on the Commodore 64 f you iiay want to let the 

LOADer use the space normally set aside for the EDITG?. for ycur program^ 

This can be done by using a bootstrap program (as described above), which 
should be zhe only program loaded (you can use a two-stage bootstrap to 
guarantee this) . This bootstrap program might have the following form; 



PROGRAM BOOTS IG OWN 
INCLUDE LIBRARY 
INCLUDE PROSYS 



WPTR=WORG 
WEOF=WORG 
WSIZE=0 
EDRES=FALSE 



Make workspace empty 

No workspace usable 

EDITor will no longer be ther 



HIFREE=MEMLIM ; Reclaim Editor's space 



It vould then Lead and execute your programs, described in the section on 
bootstrap programs, above. 

Ther ;crr pre gran returns control to the EXECUTIVE, the EXECUTIVE will move 
bac^ inro memory at OSORG* If you subsequently use the EDITor ? it uill 
automatically be rs-lcaded (from disk, for the Commodore 64) „ 



Copyright (C) 1986 SMA IiCo 



Rev, C 



3GRAMS 



command, and then type J 



BOOTBIG Progname 



from the EXECUTIVE, where Progname is your large, compiled program. 



PROGRAM BOOTBIG OWN ; Comaoda S4 ceLt bo;: , .cgram 

; Kills workspace and EDITor 
INCLUDE LIBRARY 
INCLUDE PROSYS 
BEGIN 

IF NCARG <> 1 

PUT NL, "BOOTBIG ABORTED : No name given" 
ABORT '7/CUsage: BOOTBIG Progname" 
HIFREE=MEMLIM ;The max memory please 
WORG=MEMLIM illo workspace 
WPTR=MEMLIM 
WEOF=MEMLIM 
WLIM=MEMLIM 
WSIZE=0 
EDRES=FALSE 
LOAD CARG [ 1 ] 
IF LDERR <> 

ABORT ,8 #cBOOTBIG LOAD ERROR $#H", LDERR 
END 



;EDITor not resident 
;Lcad & execute 



REMINDERS FOR SUCCESSFUL USE OF OVERLAYS AND SZP«21"S CG5^lL4^1C5 



1. The root module or modules need to expert any ^drinl ti ~ receded by the 
overlays ? and the overlays each need to INCLUDE- the exports (don't forget the 
•E extension) . 



2. Each overlay must start with; 



OVERLAY Name [EXPORT] 



and must be compiled separately . 

3. Overlays may call routines and use variables exported from the root 
module T - , -or other overlays already loaded. The root module cannot contain 
calls i: routines or reference variables declared in the overlays . The only 
way tr ^nter an overlay is by a call to LOAD, which will transfer control to 
the t ^zrj point of the overlay. 

4. Remember that if yoa alter ome sodnJLe 9 ne matter how trivial the change , 

you Mttst ?e-e@apile al l modules which aeeess it. This is entirely the 
programmer's responsibility; there is no way for FRQMAL to check it for you. 
If you fail to do this, the LOADer will relocate the program incorrectly, 
probably resulting in mysterious crashes when your program runs « One way to 
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5. If you manipulate LOFR" - - - . - . 

must always be C * 3. , alway.. 3- „~ ;.s c. ^ -s^^ /^ : -c«t- „ 

6. You should always cheer r^e r^j^e ^r arter :ali to LOAD, 
and print an appropriate diagr.-?ti- -£c:^? i~ — error occurs. 

7. Be su-.: ~ I CLUDE PROP I - -q :: — d^rrc — from PROSYS.S 

directly into your source prograx ror airy program using the loader, 

8. The LCal; procedure depends on the underlying operating system, neacry 
map and computer hardware for irs operation. Therefore you sxn±d uoc expect 
programs using 10 AD or EXPORT to necessarily be completely portable to ~thar 
kinds of comparers or operating systems, just because PROMAL is avai^ao^e en 

that computer, 

r~ i: you EXPORT anything, you must have EXPORT on the PROGRAM (or OVERLAY) 

11 . rou § et ar " ILLEGAL EXPORT" error when the COMPILER encounters 

toe firs, EXPORT declaration, A PROGRAM declaration should also have OWN 
specifier (or else the variables will be assigned the same addresses as any 
other module not specifying OWN) , 

iOo Exporting scalar variables may increase the memory usage of your 
program somewhat » 

11. A maximum of six modules may be in memory at z :\ze (8 with a program 
generated with GENMASTER it? the Developer's package} - 

12. For the Commodore 64, using LOAD with the LDPRCLR option, the LOADer 
rjiil set HI FREE back to HIMEM after unloading all programs, to preserve the 
space -ao lly croupier. ~:o- the EDiTci o If you want the EDITor space to be 

avails ria for loading tec, you need ro sec HIMEM to MEMLIM before calling the 
LOADer (Caution: rhis trill cause the Workspace ^if any) to be moved up to the 

top of memory tec, ana it od.ll be clobbered when the EXECUTIVE swaps back in), 
Your program should res z ore HIMEM before exiting back to the EXECUTIVE • 

13. if you use multiple modules and have an ESCAPE in one module to a 
REFUGE in a separate module, if you exit from the module with the ESCAPE via a 
normal END, the program will still return to the parent program of the original 
module. 
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to a - Vne statement; 
INCLUDE LIBRARY 

near the s :ert zz jour progr*- Inii s.stsr^r;:; islls :o::?ILER to read the 

definitions for the standard library. Zbrls if jr-st e 1: 5C of external proce- 
dures and subroutines. You car. cis^le;; ths lisz ;-rlth a rJPS L command from the 
EXECUTIVE • • The INCLUDE LIBRARY statement does NOT make your program any 
larger, The library routines are always present in memory: -:ha INCLUDE LIBRARY 
statement merely tells the coT^rils r whs _ tha names are £.nc ::hera they are. 

Once you have defined the routines 1:: the LIBRARY with the INCLUDE 
statement, you may freely use them in )oui program. You call LIBRARY routines 
in the seme manner as other PROMAL routines. Unlike normal PROMAL routines, 
howevery most LIBRARY routines can be called with a variable number of argu- 
ments s seme of which are optional. For example, the LIBRARY function PUT can 
have one or more arguments. In most cases, the optional arguments have a 
default value, which will suffice for most cases o For special cases 5 you can 
specify additional arguments which modify the way the routine works. 



fable Is LIBMBT StmasmiTY 



Name 


Avails 


Description 


ASOEr 


AC 




Abort program execution, optionally displaying message. 




AC 


T. 


Absolute valre cf REAL value. 




ia.C 


Ls 


Tao t it character is alphabetic. 


user 


Mi 


L 


Block tCOVS* 




AC 


L 


Compute 16 bi: checksum of memory region. 


CLOS1 


AG 


_j 


Close 3.i, open file or device. 


OfPSTE 


AC 


L 


Compare strings. 


CURCOL 


AC 


L 


Determine current cursor column. 


CUSLINE 


AC 


L 


Determine current cursor- line. 


CURSST 


AC 


L 


Position cursor on the display, 


DIR 


AC 


L 


Display file names matching a pattern 


DIROPEM 


A 


P 


Open disk directory for reading. 


EDLIME 


AC 


L 


Edit a line on the screen. 


EXIT 


AC 


L 


Exit from program, optionally with message. 


FILL 


AC 


L 


Fill a memory block with a constant ° 


FKEYGET 


AC 


L 


Get a current function key definition* 




AC 


L 


Define a function key expansion string. 




AC 


L 


Split command line into arguments. 


GETBLKF 


AC 


L 


Block-read from file. 


GETC 


AC 




Input one character from keyboard with echo to screen. 
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— — _ .- _ 












p 


j ~ r * ~~i : :. li ' - v::_al port) 




AC 


: _ 


; s t* -v. ~ 3 1 ". Cdl ~ -i; , c i _ r r : c ;s : hine code. 




AC 


L 


*--_:••'- - r: c -1:1 ~zz^zz -:"Mng. 












At* 








Ms 


T 


Concert signed "r&l'j.i a ntJing" 


JSE 


AG 


P 


lail machine language subrou ;.r.£- 




AM 




5.3 turn length of siring. 




>'■ p 






£^%J?^Bkj3» it St, 


AC 


T 








„. 
JLi 


T?p fnrn flip 1 a r a p q t of two tlq^b arguments • 


1211 


AC 


: 


Return the smallest of t^ro or more arguments. 




AC 




Load machine language program or memory image c 








String copy or subs trii ; u • •> r concateQS/cs s crinss 






- 


Tp c t if cYia - Lim e r i c • 


^ EM SsM J3&> £33 




? 


Get ProDOS volume name for specified disk drive. 


0PS1 


AC 


L 


Open a file or device for input/output. 


00TP3I 


AC 


L 


Format Lied output witli many options. 


•• .- ;.' •<;•.• JLJ&. OsF 


AG 


t=j 


Formatted output to a f ile c 




aC 




Exit f'coir PR0MA1 systsffio 




££ 


7 


Out out text tc the. oi so-lay - 


PUTBLIF 


AC 


L 


BiGck-?;rits :c file* 




AC 




Output test to e file or device. 








Obtain a p s e nd c *~ r a nd om number • 


REPLETE 


i£ 


T 


f.nnvprf ^ "^h m Y value to a stains • 


HDIEECT 


AC 


ic 


Rpdir^rt ^ rarrf a rd inDut/ output to file ds" ice . 




AC 


JL» 


JaC LlalEC C* x J» J-v? • 


SETPOSF 


A 


la 


Qo -h raoi"-e'1 iaoi ATI ' r sr " p '"andom aCCfiSS) # 
t3fcJlL ; U^. . \ w wL x l> JL LI JL LL CL J_J_A^ \ •** ^w^^sj^ / • 


SEffPHFiX A 


L 


Set the path name for directory searches. 


STRRBAL 


AC 


L 


Convert a string to a REAL numeric value. 


sam 


AC 




Convert a string to a numeric value. 


STOS1R 


AC 


L 


Search for one string in another. 




AC 


L 


Test if a key is pressed on keyboard. 


T0PPPER 


AC 


L 


Fold lowercase letter to upper case 


¥01DSm 


AC 


L 


Convert an unsigned value to a string. 


ZAPFILE 


AC 


1 


Delete a file. 



* l@te§ Avail, meaning : First column indicates machine availability , A^Apple 
II, C^Commodore 64. Second column indicates che required INC1UDF file, 
L==LXBRARY, P=PR0SYS. 
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INCLUDE PROSYS 



near the begim some 
less-f requenti: 

The LI".-,?"-"* ~ -::rn-o s -\z-~ * ~ T v ~ = column indicates which 

computer? - :*i ~:^^zi^ 9 v. ; - - - , -_„r: - : * : r "CLUD7 ~S = zz _*eded 

in crd-v: £ iz. ^ renins Llti^l!! ~r r7"ll:" 



ZQ^ 7£ 7Ss IS ZZT&kgZ icCovIlS 23 SC1ZFTI GIIS 

Iho frllo~:trg oa-tico p—id-r n iotonlsi ;5s::::;::fi of ^ach _-_ti .= 1:. 
trie LxBBA?iI r in alphabetical order c Trie oSAGE lice gives the syntax for 
calling the ::.::ns. '^zzls chctrn in CiFIIiL tSTloiS sre required 00 te -on- ed 
as sho;*r ^ai enough they do not nave oo be ty pea using apcer case leccers)* 
Words shorn ir "! o~-:sr case r ~ioh : :no first letter oepitc lized are u s 3 r s r c r 1 : o 
arguments- these srgnrsnos cnr hs ^ari^tlss or constants or more oonple;: 
expressions e argmrsnts sho-m in aarara brackets ; [ and ~ ; ars 
argument rhioh cl;- do 1 icltdec lof : .: 2 zz :rs programmer's ii€ors"lor- 
The description or cfcs routine *-.tIL tell ^oac actloas are taken if the optional 
arguments are act supplredc Ellipsis ( c : o ; are ^ssd to indicate an arbitrary 
number of repetitions of aa optional argument e For functions , the USAGE line 
will sho>; an assignment statement with the type of resulc returned indicated by 
the variable nsie* For examples 

USAGE? Pytar^r * SSTC- [i liable z] 

shows that the function GETC has one optional argument which must be enclosed 

in parentheses if given, and returns a function result of type BYTE • The # 

symbol is used in the USAGE line to emphasize that the options... argument must 
be the address of the variable, not its value. 

Some routines oars icrs than one options! argument 2 ^n #hich ease sose 

or all may be specified, It is cermissable to refer to the same LIBRARY l on cine 

with different numbers of notional arguments specified in one same orograo 
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i~o:r abort program 



USAGE 

ABORT is a procedure which does not return to the calling program hut 
instead exits to the EXECUTIVE. Optional;' - -~ -ay contain any arguments that 

are leg edure OUTPUT, which will be output to the display. 

EXAMPLE 

INCLUDE LIBRARY 

DATA WORD OLDFILENAME = "MYFILE.T" 

BEGIN 
• • • 

ABORT "CAN'T FIND FILE #S"» OLDFILENAME. 

will display an error message on the display and abort to the PROMAL EXECUTIVE. 
See OUTPUT for a desc": ; :io- " ? arguments which may be used. 



fllC ABS ABSOLUTE VALUE 



USAGE : Realvar - ABS (Value) 

Function US returns the absolute wine of a real number * The function 

returns type REAL o ABS(X) returns X if 1 is positive and if Z is negative. 

EXAMPLE is 

iiCLUDE LIBRARY 
• * • 

... i_ \. -v / 

~E iL 1" 

Z 33 a55(X-!U }/2c 



NOTE: 

1, in PROMAL version 2.0 and earlier, ABS was not included In the the standard 
LIBRARY, but was in file REALFUNC . S Instead, For version 2.1 and later, It Is 
In the LIBRARY for improved convenience, performance, and compatibility with 
IBM PROMAL . 
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TEST If CHARAC 



USAGE : Bytevar « ALPHA(Char) 

function ALPHA returns TRUE if the argument is alphabetic. The argument 
CL*::;- is -v.ipected to be type BYTE (not a strips:: . Both upper and lower case 
letters turn TRUE . 

EXAMPLE 1: 

INCLUDE LIBRARY 
• • • 

BEGIN 

CHAR=GETC 

IF ALPHA(CHAR) 



PROC BLKMOV COPY BLOCK Of MEMORY 

USAGE t BLKMOV //From, #Tc , Count 

BLKMOV is a procedure for copying a block of memory to another location. 

frras is the starting address. C&w&t is the number of bytes to copy #T© is 

the destination starting address. The block being copied can overlap the 
destination without a problem* 

EXAMPLE 1: 

INCLUDE LIBRARY 

WORD VALS [200] 
BYTE BUF[40] 
WORD 1 

BEGIN 
• • • 

BLKMOV $0400, BUF, 40 

copies 40 bytes (decimal) starting az $0400 to BUF. 

EXAMPLE 2 i 

BLKMOV #VALS [I] , BUF, $8 

moves 8 bytes (4 words) starting at the Ith word of VALS to BUF. Note the # 
operator before VALS which is required for proper operation. 
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ftoc ghksum 



USAGE : Wordvar = CKSlM(#Start _ 

. - 1' "^"'r" 'f c : :f r-ytef" aemory 



checksum. The 



EXAMPLE 1: 

INCLUDE LIBRARY 
• • • 

BYTE ARRAY [1000] 
WORD ARYCHK 

ARYCHK - CHKSUM( ARRAY : 1000) 

IF CHKSUM( ARRAY, 1000) <> ARYCHK 

PUT NL, "ARRAY has been modified 1 



mm close 



CLOSE FILE OR DEVICE 



USAGE : CLOSE Harris 



CLOSE is a procedure which closes a specified word file handle. The 
argument Handle must be the handle fci e previously opened file. 



EXAMPLE 1: 

INCLUDE LIBRARY 

WORD IMP of FILE ;File handle 

BEGIN 

INPUTF ILE=0PEN( IMPUTE ILE ) 

CLOSE INPUTF ILE ; Done with file 
• • • 

It is not normally necessary to close files in a program since all open files 
will be closed automatically by the EXECUTIVE when exiting from a program. If 

you are planning to generate stand-alone application programs which will be run 
without the EXECUTIVE (as described in the PR0MAL DEVELOPER'S GUIDE) s then you 
should be careful to close ail files, since they will not be automatically 
closed. Also if you work with several files in a program, it is a good idea^tc 
close a file as soon as it is no longer needed, since a limited number of files 
may be open at once. A power failure or other system failure may leave a 
file written to disk incomplete unless it has been closed. Be careful not to 
close a file which you have already closed previously* 
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7~JMC Off SIM COMPARE STRINGS 



USAGE : Bv z „ ^ L_ - r - 



Function CMPS~: — ir^r^ ~r z — — Jtitl^I J;— ^ us :he address- 

specifying which - zj ^ ; ~. - j f -> ~~-f -_v, ?TFJ - 

"<" "<=" "<>" ">=" 

T - r - - ? 5:- ct'ricr^L 1c cle£,r, 'EITZ. srg^nent default i::- to FALSE which, if TRUE, 
-s.^S3 let :e:i i :. . 1~ icr.sidered as equal to ths„r ^ :^e: case 

e:,-! "E^e" — Lisilt i r a:„ ^pri^ai Ergr^svc :: ihri "he caxiinun: ::;^;;ar of 
chariEccara t:: ccnrara s:ri-g : c-f $ -„lLl..:g .: : 2~3 The collating sscusnes 

- '". z- ~ ^ 'i z ~z ..: i s : z is .:. - i^r. , ... _ .'i:cCC5" a ■-. " - ~. : v^s r,6 r-.c i-i 1 _ 

c:ii;~ if chej are the sane length and have t™=> se^e concent (cr eoui"al.e~ t if 

is IF. IE ) • If twc shirks _ .recent lengths match up l z. z'ze end cf 

shower seriog, the longer scri-ig is considered greater 

Ll/>l?LI 1 ; 

1111111 LIBRARY 

• • • 

BYTE ^INS[3ij 

• • • 

GETL ajj_I\E 

IF CMFSTR (LINE, ">", "M") 

lasts if ths string LINE is gra^tar than "M" . 

EXAMPLE 2; 

DATA WORD KEYWORD="DRAW" , "MOVE" , "ERASE" , "QUIT ,: : C 
1=0 

REPEAT 

IF CMPSTR (LIKE, KEYWORD j. 1 j * TRUE, LB N5TR( KEYWORD [1 ] ) 

I-I+l 

UNTIL KSYWCRD[l;-0 

tests if the string LINE matches the Ith keyword of a table, up to the length 
cf tne keyword* (Ncce: See function LOOKS TR for a better waj to do this). 
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F11C CURCOL 



USAGE: Bytevar » GTOCOL 

Functi:r. ^TLlZh returns the current column number of the text cutx - - 
screen. The leftmc . -::-lum 2oli-:*r: . ~:»t column number 1. 

EXAMPLE 1: 

INCLUDE LIBRARY 

• 9 • 

?A 

CON MAXCOL = 73 ; Screen 1„ -xple 

? 

?C 

CON MAXCOL = 39 ; Screen ~ 1, Commodore 
? 

BEGIN 

IF MAXCOL-CURCOL < LENSTR (STRn T ^- ; wot : -itirely on current line? 

PUT NL 
PUT STRING 



RETURN CURRENT LINE NUMBER OF CURSOR 



USAGE : Bytevar = CCfiLlIS 

Function CURLINE returns the current line Hunter c ? ihe text cursor on the 
screen. The iciest line is lies \ : zcz o. cie number ~. 

EXAMPLE : 

INCLUDE LIBRARY 
BYTE SAVELOC 

• • • 

BEGIN 

• • • 

SAVELOC=CURLINE 
CURSET 0,0 
PUT "Error, please 
CURSET 0, SAVELOC 



;Save line we're on 
;Move to home position 
try again. " 

;Back to where we were, col 1. 
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mm curset 



USAGE ; 



CDR£ 



e 



Pr 




exampl: 

INI ^ 11 ^lll^lY 
BYTE I 

BEGIN 

curse": ; ;: 

moves the cursor to tre iz~~az of text row 1 on the screen. 



USAGE i Int-ar - PIR(Patterti t s Modej; 

Function DIR displays the names of any files In a disk directory. For the 
-ppie II, ratters Is -he desired directory name • rlc filenames or wildcards are 
recognized. For the lunmodore 64, Pattern Is &. filename seeing which may 
Include wildcards * and ?. The Pattern may cr :lcnaily have a drive number 
prefix and a file extension (which can also be a vl ldcs.rd> ~ The * wildcard 
matches ANY ?crlx£ ?nd the ? wildcard matches • single character. The 
function rsc^is an INTeger value indicating the rosier cf files which matched 
the Pattern . : neluding subdirectories fer ths Apjle^ if positive or 0, or minus 
an error code if negative. The absolute valta of the errer code has the same 
meaning as for I0ERRCR for : c -mction OPEN. Mecs Is en eril-nal argument, 
defaulting tc e If Ifede Is 1 or unspecified : a Vermel display of file names 
is made. If :&>de=G 5 then the directory will be testec fer etching entries and 
Intvar returned, but nothing will be displayed c Alternatively. Mode can be an 
open file handle. in this case, the output Is directed to this file or device 
Instead of the screen. 

For the Apple II, the f erase of the output display will be the same as for 
the FILES command In the EXECJTI IE If the output Is to the screen, or will be 
one filename per line for any other file or device, for the Commodore 64, the 
format of the output display vrlii be the same as for Commodore 3ASIC. The 
pattern matching Is performed by the Commodore ROMs resident In the disk drive, 
and therefore operates as described in trie Commodore disk manual. In particu- 
lar, you should note that a pattern cf S ***S" will mot match all the files 
ending In ".S", but will Instead sacch ALL the files on the disk. This Is 
because Commodore has chosen to implement the "*" wildcard to mean, "match 
anything at all" (including "."). 



FUG ME 



EXAMINE DISK DIRECTORY 
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BEGIN 



xists? 
e?" 



DATA WORD SUBDIR="ACCOUNTS/ " ; Sub-directory in current prefix. 
WORD NUMACCTS 

ICii-l.. C 1 --Ilk ' £ -""311k ■ - i zsy ills rae- in our sub-directory 



NOTE : 

1. Jc- che Apple, any file name part will be ignored. For example, 
" 2 : ACCOUNT S/MYF ILE . T " is equivalent to "2 : ACCOUNTS/" . 



FUNC DIROF1M .1FFLE 11 QJSSLZ OPEN DIRECTORY FOR READING 



USAGE s handle - BIECrPSl^B? rnaee [ , Mode] ) 

F-nec-c* ll^Okk^ la 1 o,:er. a ciek director j for reeding c:i Icie i^p^ls 
II. is a spring specifying £hs directory rwie. Mode is tie cplicnal 

access mode character, fksiick nuac be "Bk {read access) if specified- Opening s; 
directory zci ^riti^g Is nc: tsni':te£ by ProDOS* DXIOPEN returns e file 
handle 7 '11.1 v es £ . * :rrifl Hill -z:::^"L::n. If ^ucees^f j.1 - kr-cs :?3is:, 

tha dirsc cor;- .-.an be rafl like s.n ordinary file- Pieasa consult eke ?roDCS 
reference manual for information on directory organization. 

EXAMPLE 1: 



INCLUDE LIBRARY 
INCLUDE PEOSYS 
DATA WORD PATH = "2:" 
WORD DIRHANDLE 

BEGIN 

DIRHANDLE = BIROPEN (PATH) 
IF DIRHANDLE = 

PUT NL, "Can't open directory for drive 2" 
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NOTE : 



EDIT LINE ON SCREE1 



USAGE ; Bytevar = EDLINE irrir-g ^llr^: ~ riz^ " _i; " ; 

Fun or -.or. EDLINZ Is usee is atloT ecr;:lc§ -f a single line of text 

in the same way as is supported by the 711.:a.1 IdECJTlllEh Siring Is roe address 
or ina so • log to be displayed and edita-' ir c„2c.a- drrisg snc 3 it: be :l 5 
addrsss of s ~ of f er large enough to hol£ Isset Lit^ii4»l ^kerscte^s Liait If 
a:o ~ o '.i it na 1 T*r rax a tar d e f a 1 1 o i o o ?'l ""hiro is ~~y a i£r„*: n :c , i t^^sr co c"harac~ 
tars acceptable In the ii~ie- Mode is options! argrcaent def avoirs to $00 



jzb ossac ^r.oo or to .i a iicc^c as ;:^„C7S-! 



-i; C = 1 ::iods-SC:; nes-s display the lira ir. racers- -ides ; highlighted) . 

Z £e£r»& display cha lice i-~ -:G::oal cldec^ 
lit 1 = 1 (Mcde s S02) irearis return '"rr*"' far o tior. :;sy cede? froc -he hayboard . 

means expand the function keys to their current definitions (see 
f KEYSET) . 

Bit 2=1 (Mode=$04) means return "strange" control keys (explained below), 

means ignore "strange" control keys 
Bio 3-1 (Hode-SGSy xaao.s initially display crrscr at aha coia^a specified 

in the BYTE variable QqI. if specified 5 otherwise at the first 

character* 

seatis initially display cursoo after last character* 

The lasc optional argument 5 §Gcl, is ignored onlaoo bit 5 of Ilofe is h In 
this cssSe fOol is the sieress of a variable of cype 31TI vhich coots ins the 
desired starting cclunrn for the 0:00000:0 If the specified cod, oooo is greater 
than the length of the lire - the crrsor t^rll re posits cned lemediatsly after 
the last character. On exit from EDLINE, the variable Col is updated to the 
position of the cursor at the time of exit from EDLINE . 

Mode bits may be combined. For example Mode=$09 enables reverse video and 
positions the cursor at the start or the field instead of the end (assuming no 
#Col argument is specified) * 

Function EDLINE returns a byte whicn is the terminate r entered* Fcr normal 
Mode, this will be a carriage return ($0D) c However, if bits 1 and/or 2 of 
Mode are 1, it could be a function key, cursor up/down key, control key, etc. 
"Strange"' control keys are defined as those control keys which are not allowed 
for line editing, or keys returning a value greater than $7F other than 
function keys. See Appendix 1 fcr key code values, for the Apple s function 
keys are defined as either Apole key in conjunction with a number key i though 
8. 
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I'o'ce. th^c during inpu^ : ths lure:/! Is held "capti-'s" 1 i n the limits ci ths 
iLTioj tasking it suitable for varices kinds of data entry* r>y sstting Med© 
sppropr lately , EDLI&E car? heeone the basis cf an sdiccr or f leld-crisnted data 
sncry system By sszztng bi:s I snd 2 (Mods=$0S-r?C4; and specifying #CgI s ycu 

returned by the function) , and what column the cursor was 1.2 at the time 'by 
the l':e returned in Col). You could then c;sli EDL15E sgEin tc adiz a string 
which is on the line above the present line on the screen, witn the same 
argensnts. and the cursor would appear initially in the same column as on the 
previous line. 

EXnMPrE It 

INCLUDE LIBRARY 

BYTE DUMMY 

BYTE BUFFER [81] 

BEGIN 
• • • 

MOVSTR "ERASE " s BUFFER 

D UMMY= E DL I li E ( z F E 51 : let user complete or change the command 

This program fragment will display the word "ERASE" on the screen, followed by 
a blank and the cursor. The user could then complete the command as desired. 

EXAMPLE 2; 

INCLUDE LIBRARY 

BYTE LINE [41] 
BYTE COL 
BYTE KEY 

MOVSTR "This is a line to be edited.", LINE 
C0L=3 

CURSET 3,0 

KEY = EDLINE(LINE, 40, $0F, #C0L) 
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USAGE j EXIT relist] 

2111 Is fi : ;rccedu::c- rricr 1.^ *cL . iturn to the o&U: rg src-gr^i c-sc 
... ircsaci scl"? : : :he £!3C % :^l-3 fcr t u a parent progr?^ If :hi? ^rcgrst-i ; %3 
" .1 w~i mother; c IriirrsJ rhs rsll may contain sr§eisiils del ^-:e 

1 fcr r :-ocedure OlTT^CTc .-ill ba output to -lis^lay - 

EXAM ~ " , 

INCLUDE LIBRAE! 

BEGIN 
* • • 

EXIT "Program Complete. M 

111- "ill display a message on the display a ;.c ^:it to the PROMAL EXECUTIVE. 

lv,e ;i vcedure OUTPUT for a description ■■ -~l~.e c arguments may be used* 



3201? ^HH FILL A BLOCK OF MEMORY WITH A CONSTANT 



Tlrllr jil^ 'l'::n, Court ; r Byt3val] 

FIL1 is € procedure which fills a block of memory with a specified value of 
type BY1Z -ITr^c is die desired starting address c Coust is the number of 

bytes to rillo The optional argument lytewal is the value to be placed in each 
byce 5 defaulti-g to $00. FILL operates much faster than a programmed loop. 
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EXAMPLE 1: 



INCLUDE LIBRARY 
BEGIN 

CON BUFS12E » 
BYTE BUF [BUf SILL ' 

FILL BUF, BUF SILL 
zerocj array BLL vi -Li.^ BUF SIZE bytes . 

EXAMPLE 2: 

BYTE MYSTRING[20] 

FILL MYSTRING, LENSTR(MYSTRILLT- : " ' 

blank fills the string MYSTRING up tc its present length. 

Wrsr. :,z^~ig FILL to zero ar~&;7 :f ryrs WORD or INT, remember thai the sir-e 

needed f : r •:. :ie second argument should La t;clce t~i3 array dimensi" 'V1-7 iijrss 
for L..L-LL _ 7 - 



1?UDC GET A CURRENT FUNCTION KEY DEFINITION STRUG 



USAGE: FKEYGET Keynumber s ^String 

Procedure FKEYGET sets a string to the correctly-defined function key 
substitution string-- Isj^a-asesr is the desired function key number, from 1 to 
8. fStricg ie the address cr e buffer Ls€s : ; 2 characters long to receive 
the desired string. 

EXAMPLE 1: 

INCLUDE LIBRARY 

BYTE KEYDEF [32 ] 
WORD I 

• • • 

BEGIN 

• • • 

PUT iL'The current function key definitions ares t; 
? > I TO 8 

- LYGET I, KEYDEF 

-uTLUT "#C#I = #S" , I, KEYDEF 
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MOTE % 

1. To define function key 

2. for programs created w 
Develop-- - functi'" 
defined by calls to F KEYSET. 



-rr^-s,- DEFINE A FUNCTION KEY EXPANSION STRING 



- .^•■ir.. heynumber , String 

Procedure f KEYSET is used to define a f:.-.:Li;r. nej ~~.bstitutioo string ci 
up ic 51 characters. Keynumber Is the desired fmccrer -rey number f 1 to 
String is the desired function hey subsiit^ti^c string- 

Once the function key substitution string is defined, pressing the fraction 
key In the PROMAL EXECUTIVE , or during data entry to a GETL, EDLINE "LINE 

call, will cause the defined string to replace the current line. Up to 51 
characters may be defined. Only normal, displayable ck"°r.*i = :? ''"hrough 

$7E) should be used. 

EXAMPLE 1: 

INCLUDE LIBRARY 
• • • 

BEGIN 

F KEYSET 2, "COMPILE 2:MYPR0G" 

defines function key F2 to be "COMPILE 2 : MYPROG" . 
NOTE J 

1, On the Apple ll 2 rcrction neys are activated by holding down either Apple 
key and pressing a number hey 1 through 8. 

2. Yon can Ignore function keys In EDLINE/ INLINE/ GETL by using F KEYSET to set 

the key definition zc e null string (e g~ r f KEYSET 1,""). 
3 • You can cause the function keys to return cheir original key code In 
EDLINE/ INLINE/ GETL by using F KEYSET to define a string consisting of the key 
code (see Appendix 1) followed by a zero byte ' s <> g e r F KEYSET 1 3 S8 \85" for tHe 

Commodore 64 Fl key) o 

4. function key settings defined In a program renain in effect when control is 
returned to the EXECUTIVE « 
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nb^i :-:£76':^v is ic la ccn?iisr~d the asperate^ :f srgcusr^gc Tiis -S2TARG8 
f :.on ^ill ^edify the itrgliss string in pises 5 : ; installing -s C 'zy'c- ?: ::-6 
sad -f -aci ergnnent, replacing ths first separator pjis-ailj a hiaiih} alter 
each st.-g^nsnt: . Each entry in ths pointer list """ill he filled *ith a pointer to 
tbs :• v^" : ^n-blank chars/- ;~ . : ..ne argument. Th- „e^- aed val-~a sf tha 
function is a BYTE variable indicating the number of srgenents returned in the 
pointer list. 

EXAMPLE 1: 

INCLUDE LIBRARY 
BYTE ARGLINE ~ £i : 
WORD ARGLIST _ . _ 
• • • 

BEGIN 

MOVSTR "MYFILE 6 YOURFILE% ARGLINE 

N - G3TARGS ( ARGLINE , ARGLIST ) 

will return K«3 f and set 1RGLIS i [ 1 ] - "MYFILE" , ARGLIST :i \ and 
ARGLIST [ 2 ] = " YOURF ILE " . In an ??-n?l application; .1RGLINE would typically 

be read from the keyboard instead. The effects :«t GETARGS on the AKGLiNE array 
in memory are illustrated below (0 indicates $GC terminator) : 



■ — , • : ,' ; » - ' , ? - 

sMjY|F JI|L |e| j j j j !*t !*jojU*fR*|FjljLjBjOj Before GETARGS call 
ARGLIST [0] 



1 



-ARGLIST [1] 

- r 



5 ——-ARGLIST r 2 « 



|MjY}F!::[ljE Of j f j |5|G|Y?0|U|R|FjX{I,|S|C Af:sr GETARGS call 



1« .since the Argline string Is modified in place, if you alter any of the 

springs returned in ARGLIST, you should be careful not to make them larger or 
they will affect the content of neighboring strings. 
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F1HC GETBLKF 



-V--' - /*■"-. FROM A FILE INTO MEMORY 




:-L£^s^£s, I ,.-..r..:. ^z z-:zz -ril^ ~"r£ er:rr.r:- ed rsf.rrs ¥iszmzz% 'zyzz-i zzz„z is read . 
GETBLKF dees ;.: •: recognize any record boundaries or delimiters except 
end-or-f ilec It is the complementary function to PUTBLKF . 

it is the fastest \zay to read dats from disk* 



EXAMPLE 1: 

INCLUDE LIBRARY 

• • • 

WORD SCREENFILE ;File handle 

WORD READS IZE tit bytes actually read 

• • • 

BEGIN 

• « • 

SCREENFILE=OPEN( "SCREENDATAo } :0?sr for reading 
IF SCREENFILE=0 ;Open error? 

ABORT "#CCant read SC RE END ATA = tl rile; : " 
READS IZE=GETBLKF (SCREENFILE , $0400, 1000} 



reads 1000 bytes 'decimal} from the file "SCREENDATAoD" into memory starting at 
location $0400. 

NOTE : 

1. The predefined (in the LIBRARr"; ariable DI0ERR0R can be checked after a 
GETBLKF operation to test for possible errors, if desired. if DI0ERR0R=0, the 

read was completed normally. If DI0ERR0R = 2 : a disk read error occurred (In 
which case GETBLKF rJlil return as much as could be successfully read before the 
error) . 

2. When using GETBLKF to read data into memory starting at a particular 
element of an array, be sure to specify the # operator to indicate that you 
want the address of the array element . not the value. For example, 

READSZ * GETBLKF (HANDLE, #BUF[I,0] ) 

3* IMPORTANT s For Commodore 64, GETBLKF is the only Library routine which uses 

DYNODISK, If It is enabled. You must not mix GETBLKF calls with other, 

non-DYNGDISK read calls (such as GETLF or GETCF) on the same file while 
DYNODISK is enabled. Also, do not mix GETBLKF calls with DYNODISK off and 
DYNODOISK on In the same file. To disable DYNODISK from within a program, set 
C64DYNO to (defined In file PR0SYSoS)o 
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F11C GETC 



USAGE J Bytei 



the same statement. Gzu'-r ^ v'.r^--:-*- tae cur so i 

pressed, and echoes tne x&,;: :c :he screen. 

Q^IIGS; If y::-.:. :hi ;ional s=-.v: ^ . — to specif;" ths ? 

o--:-':c- — — t-f ^T^f.e to r^ ..e:. --vr e.f;^':- Otherwise, the 

c^.r£o:-r "^e l-et^il-.? r^^whers in i~he fir^ of memory, correspond- 

ing to whatever val^s happens to be in -cri-.lf % "he time, possibly 

corrupting the PROKAL system. 

EXAMPLE 1: 

INCLUDE LIBRARY 

BYTE NAME : m 
WORD 1 

BEGIN 

1-0 

'JalLE. -L PHA( GETC ( #NAME J 1 : > } 

:Li21ih ~"^3 

This -Plls the buffer NAME ri:: characters froji the keyboard until a non-alpha- 
betic character is entered; snc 1 terminates it ciith e S00 byte to maxe it £ 
string. Alternati -ely r ^ fr--?r without a 7 - argument could be used; 

1-0 

REPEAT 

~~*7 I =GETC 

I i*n I « ALPHACBUF^I-ir 
BUF[Ij=0 

NOTE J 

1. GETC processes the Alpha locic key (CTRL internally ^ 

2. GETC treats CTRL-Z as" end-of-f lie from the keyboard and therefore returns 
$00 instead of $1A for CTRL-Z . 

3. If you wish to get a key without Keyboard echo, see GETKEY* 

4. If you wish to test if a key is pressed without: siting fcr cne, see 
TESTKEY. 

5. It is possible to change the cursor blink razee See appesdlx Ce 
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EXAMPLE 1: 

INCLUDE LIBRARY 

BYTE CHAR 
WORD INFILE 
WORD COUNT 

BEGIN 

COUNT«0 

INFILE=OPEN(CA-iG: 1 ) ; 
WHILE GETCF(INFILE j #CHAR) 

COUNT=COUNT + (CHAP.~^ r " ) % bump cocn; If is 
OUTPUT S, #C#S contains #W commas . " , CARS [1] , JOUNT 

This wi : ' ead the file specified on the command line and display a coun: f 
all commas in the file ■= 

NOTE: 

lo GETCf is net United te reading is;:": i^lssc It "d 11 correctly return all 

256 possible values which ecu 1c: :scc Iron ^ f ^ including $00, 

2, If the handle Is STDIN (the ^syloerc; s tlier: characters are processed as 
described for GETC above, and GETCF returns TRUE when CTRL-Z Is entered. 

3. On the Apple after G5TCF returns, DIOZRR *ill be normally and 2 if s. diss 
read error occurred. If ycu wish to check ito 



FHfc <3it^£ RETURN ONE CHARACTER FROM KEYBOARD WITHOUT ECHO 



USAGE i Bytevar - ^Variable)] 

GETKEY Is a functi on (net a .procedure ! ) which gets one character from the 
keyboard without displaying It on the screen. It has one optional argument 
which Is the address of a variable to receive the value input, it returns an 
argument of type BYTE, which Is the character read. The same character will be 
Installed in the variable whose address Is the argument, if present. The 
optional argument allows a convenient way to save the character and test it ir* 
the same statement. Appendix B gives the key codes returned by GETKEY. 
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EXAMPLE 1: 



11CLU.DE library 

P s any key when ready, or * to exit." 

IF GETKEY = 

ABORT "#cProgram terminated." 



V ^TE % 

I- GETKEY processes Alpha-loJ. ' A" internally. 

2c GETKEY returns CTRL-Z as SiA ? without special treatment. 
%- You may alter the cursor blink rate. See Appendix S* 



p R0 C GETL GET LINE OF TEXT FROM KEYBOARD 

USAGE : GETL #B'if f er ■ - Lixi ; ] 

Procedure GETL inputs a line from the keyboard, allowing all editing 
(backspace, etc.) supported by the PROMAL EXECUTIVE prior to the carriage 
return, GETL has one required argument which is the address of the buffer to 
receive the linec ^ second optional argument can be rsed to specify the 
maximum number cf characters to be read. The defarlt limit is 80 characters. 
The line -Jill be returned as a string, with a $00 byte replacing the carriage 
retur. c. 8 1 che end of line. The carriage return is net returned « Therefore the 
buffer Zor. ^-.he cef-ult GETL should be 81 bytes long tc alio- for the full 
input - 

EXAMPLE 1: 

INCLUDE LIBRARY 

BEGIN 

BYTE LINE [81] ; Input line buffer 

BEGIN 
GETL LINE 

This inputs a line from the keyboard into the LINE buffer* 
EXAMPLE 2 1 
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each 



40 

the PAGE array, up to 



^^^cccrc c-; r.3 z ^ c«siaCCcid , o. r " r r-. -r. actors rrr ~re i-^r^r L_ 

i • ~ ~* "^cisii^e L: ^i-rr the c^f:. ri_rk rate >_r_ 3it;rirg ns/s csei by 

GETL. See Apperr - 

4, GETL always alas." 3 £ span* cn ;he ^rsen largr en* rgl. 1- £n.t^r >iit 
characters by o . c . , _ . ^ -L^r-c- ... resent c s :-r ^sirirr. ^eicre 

accepting input cet tiie original cursor position) This ;na~ cause the sc:een 
te scroll if t^e >:I;Isl crrscr coition was withir lir.:. ; jh^r^c^irs nf tne end 

ci -;he screen. 



rSSC SxlF GET LINE Of TEXT FROM FILE OR DEVICE 

USAGE : Flagb;: - SZLF "bridle, #Btn:C-r ^±7*1 z]j 

Function GETLF (not a procedure;} inputs a lir,e frctc £ file cr device 
specified by the file Handle, which is the first argument c See OPEN for more 

information 011 file handles. The second argument is the address of the buffer 

tt r>»e 11ns- -j:. cp ::i.n:r „ chird argument can be nse; specify the 

nsxinrt: nrnrer cf rrsrsctsi^ tc c~ returned. If the line ccnteins £C re than 
Liant characters : the entire line is read up to and including the carriage 
return. hrc enly rhe fi-st Li nit characters are copied into the buffer. The 
lire -ill ten nir^'-—: -7 $^ v ^t? and will net include the carriage return. 

The returned value cr tre function Is TRUE normally and FALSI ( C ) If 
end-nr-flle fas encountered before any bytes could be read from the file or 
devr.ee c 



INCLUDE LIBRARY 

• • • 

WORD INPUTFILE 

BYTE LINE 1 41] ; Input buffer 

• • • 

BEGIN 

• • • 

iNPUTFILE-OFE>; ")£Y?ILE . T" ) 
IF INPUTFILE-: - open error? 

ABORT "#CCa-.' - open MYFILE . 7 - Program Aborted" 
WHILE GETLF ( INPUTFILE , LINE , 40 ) ;c nly 40 chars max please 

PUT NL, LINE 



This will display the firsr 40 characters of every line of file MYFILE. T. 
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• - - - - - - ? - ^ ^ - ~ & ~ ~-s.~~>zl*-«--0. pxoe^t"s the address 

of the desired destination . . _ lug. 



fPi^j ,^TPGbv -*_.-> L^f^IZ; LI ^^wS, ^ RETURN PRESENT FILE POSITION 



USAGE : Wordvar = GETPOSF( Handle [ ,#Seg v^r 

Function GETPOSF retu:i£ z>- rsl^i-s 
read/writ zaz ~z , ~~l~c ii^ils Is fil-= 
JiL~- /L-td^r : e ^:urn^ ^ ^ .a. ^Z~z - zlzza 

s iv rytes f :::m . - ; r .: - Vfeg^cr -3 > 
'■^■r-lr.bl- ;o receive the hig^ o ::£?:" 16 bins of -.:L 
.::s^a?ss.r; to specif j #Segvar c i:f . ' if tn^ zZlz, is 
you wish to know the full zfzeez L: ...e _.Le fil^c 
devices . 

;.. jmmon use of GETPOSF Zz zz zzz. rfa current file positi ~ for e f: ~ 
which has been partially read hut mus: ;:s closed temporarily for sc^ -eason 
(such as changing disks during a sir.£_e -rive copy operation), and then 
restorir-: zvz . ' e same position so that you can continue reading. 

EXAMPLE 1: 

INCLUDE LIBRARY 

• • • 

WORD CURPOSN 
WORD FILE 

• • • 

FILE=OPEN( "MYPIf E df : \ 1) 

CURPOSN=GETPOSF(FILE) 

CLOSE FILE 

FILE=OPEN( "MYFILE • D" , R) 

SETPOSF FILE f CURPOSN 



1. This function Is net supported on the Commodore 64 because the Commodore 

hardware and ROMs to not support it 



r :: ' ~ ,ext : jz:<:. - 
1 ? zz z ■: e vi c n.s \i~ n ?i zs z 

zzzzt^I z^'dzz^d - f -5 v^;.r~:. 
e rel&tl'/a r f f s 3 It is 
lic r ~ ;h^r "I-K bytes Irdg £nd 

ehould not be used for 
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FUNC GETTST 



GET T DEVICE STATUS 



USAGE % Byte" 



Appe „ _ .._ . Dntains additional information on GETTST and related topics. 

EXAMPLE 1: 



INCLUDE PROSYS ; Where GETTST is defined 

WORD COM ; File handle for serial port 

BYTE CHAR ; Received character 

COM = OPEN("T", 'B') ; Open serial port for incut/output 
IF COM=0 

ABORT "#CUnable to open serial port" 
TDEVRAW=$80 ; Enable "raw" serial ino^'c mods (see Appendix F) 

REPEAT 

IF GETTST(G) ; Character received from serial port? 

CHAR=G3TCF-;C0M) ;Gzt it 

PUT CHAR ; Display it 

UNTIL TESTKEY ;Dc It until any key is pressed 
CLOSE COM ; CI^ss the serial port 



NOTE: 

1. You will need to have INCLUDE PROSYS near the start of .cur program in 
order to use GETTST. 



FOTC GETVER OBTAIN PROMAL VERSION CODE 



USAGE : Wordvar = GETVER 

Function GETVER returns a WORD value indicating the version cf PROMAL which 
is running. There are no arguments. The low byte of the returned code is the 
version number as two hex digits (foi example, $21 for version 2d) * The high 
order byte indicates the target machine for the PROMAL runtime package, as 
follows; $01 - Commodore 64, $02 = Apple II, $03 = IBM PC small memory model, 
$04 = IBM PC large code memory model. Additional codes may be defined as 
PROMAL becomes available on other target machines. 

EXAMPLE 1: 
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p f :; . ' : r 5-rr rh~ st c * ~ r ~ . " - program in order to 



INPUT Lifti OF TEXT FROM SCREEN 



USAGE : Bytev = r ^ i:ihENE( Strin hl~--" ^l^z^Hl 

Function INLINE is the same HDLINE , exceo: :rat the String to be edited 
in place is automatically set to null sr the star , cf ;'ne routine. The String 
argument should be the address of a buffer large enough he herd Lis^t-rL 
characters c Ilaase see EDLINE f~rr z full description. 



FOTC INLIST SEARCH LINKED LIST 



USAGE : Wordvar - 1IILIS1 Siring, Listend [,Fold |,Lir±t • , Ssfetjh T * 

Function IFLIST is a. crscisl pvrrpcss routine far advanced programmers e I;: 

searches a Irrrrr r liar cf £ rpaclfi;, J : .r.- for ar rrtrj rrrtchr-rg z -r;;:. .c : _r 
the scrir.g is hoc icccch Z is rctcrnco- hthcr^isa ; tire redress cf the altering 
string is're^rrriar ~ String is ihs crricg desirado Liscssd is > pester to ths 
er^ cf t r.r Iter., £3 sneevn cslcr? t i=e= £ rhe lick rc ire r 1 :.. & ': r^ica :c cry rr rLc 
wcr i zz irrrccd-- The option** -rgr-err 7o.hr - ff^sh i^rhtirc ?.hhch : 
which if cet :r TRUE indicates tec.;; Lever zase Errr^^eric cr^r^cters should be 
considered as matching their uppercase equivalents, LLrr_ z ic sr. optional 
argument defaci-rcg tc 255 : radicating the maxinrri rcctier cf characters 
required to m? tec rr. String. Safety is an optional argument defaulting to 8192 
($2000) indicting tee maximum number cf entries tc test befcre giving up a 
Safety prevents cae function from "hanging up* c forever if tna linked list ic 
corrupted c The ess -red fcrtiet of the linked list is as fellows: 
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Add re 



tes) 



First Erv:^7 i :zzzg M Iz^z^z^ 



$0000 (2 bytes, beginning— f-li—r sentinel) 



EXAMPLE 1: 

; Tzz 3 zziz^zxl^ .-Lows how to t „z.i. ' _ ^z,z r 7z ~ f _L; .:• L I-^LL-i I*zz a 

; compiler 3 ^ssetabler, etc. u^ing a linker lisc, ivLSre each entry 

; i? z v*ri *ble--length name ar ~ : ^: 'zzzzc: ztz7 LsL: r.^ - >-~ ;-*alue) . 

ILTLLIL PROSYS ^ -here INLI : L; i€ zzz,-„zd 

'"'III ILHXAB [100C_ L: I LL^r li^; 

-C<£ LIS TEND Lr to next unused entry 

Insz&LI ^£>«5 : "inLUS into symbol table linkac. 
-rS. j "ILL " "-j. T ^ rLi'LCi to install 
:^F:S : LLSL 'LiLLI ; ~s~- :iated daf i^itioc ;:.ame 

WORD j^l _ 
BEGIN 

MOVSTF V.LI " ,:7Zm ; 1-f^Ll ;-ame 

STPTR= . z: c ? ,L^j i;)+Li-iLi* ; after r^ns ferine 
MfSTPIL]-' — ;i - - 3 Lr.-':^^L Ljw byle cf value 
M[STPTL-rl>'-LUI . ; : e_ Li --re 
M [ S TPT? -rl i'lLJZ < 
M [ STPTL-LL t -LIS „ V 

LISTEND=STPTR+4 : next available location 

END 

FUNC WORD GETST ; NAME 

; Returns value stored in sy~tcL zzzl- 
ARG WORD NAME ; name to look uc zz syxzhc 
WORD ENTRY 
BEGIN 

ENTRY=INLIST( NAME, LISTEN!^ ; search List 
RETURN (ENTRY+LENSTR(ENIRb" % ~L r - -&L;i 

END 
• • • 

I Inic^c szcLZz zz _ _ o- ..1 zcir oymbc u £, ^ := <? « • 

SYMTAB L j=0 ; end of List sentinel 

L I S TE ND= S YMTAB-i-2 $ starting address 



LAME 
zezDle 



zzz z..zne 

zzz FAME 
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NOTE : 



XfLlST. 



FOTC IHSET TEST IF A CHARACTER IS IN A STRING 01 SET 



USAGE : Bytewzz - Jz2Zzz(Chat $ String _ ''izzz[[. 

Functi . , _ rns the position of a specified character in a string. 

Char is the desivad character, String is the string to search. TmZ& is &r„ 
optional argument character, which is usually if specified, if :^t& Is 
specified, then z:j^ ZC&Z&. character can be used to denote a rang' c 5 -zz^z^zzz? 
Bytevar is returned as if the character is not found in the string, or as the 
index to the etching character pirns ona if -he character is found in the 
s triage 

EXAMPLE Is 

INCLUDE LIBRARY 

• * • 

BYTE GEAR 
BYTE I 
« • • 

BEGIN 
CHAR='A' 

1 = INSET (CHAR, "ABC") 

Thi- z^zczzs 1-1 because the A ma.tcLs» ilrsl c.£i"ct,^ci ^1 t^c; &i.jmg. 

••her: :feis nc^ -pecif iei.. 11SE1 sft&n used t:o find £ particular delimiter 

in c string? 

WORD L1'€E 

• • • 

LINE="100, SPRING INVENTORY" 

• • • 

PUT LINE+INSETC, %LINE) 

This will display: 

SPRING INVENTORY 

because the INSET function returns the number of characters to skip aver to get 
beyond the ccstrza. A different use for function INSET Is to test for membership 
of a byte in a sec of bytes : 
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EXAMPLE 3; 

BYTE LINE [80] 

if ~r.r<-: i:/; : -_*: _ , "A-za-z0-9.", - 



FEW IHTSTR COETrrr INTEGER VALUE TO STRING 



USAGE t IWlWm Value, #Var [ ,Ra,;iz r/:tir_fislc ^ Padding] j j 

Procedure INTSTR takes e signed value -no generates the ASCII st^irg 
repress the "Jck?c ^alue is the desired value to enc r ce snd ^vsr is ;he 
address of tr.e buffer ro receive the ASCII characters • fedis : ! s the optional 
base tc - sed^ J r^;::h„g t: 1 Ch rZiaftsll is tie minimum llslf :ddjh tc 
generate- derEc^trng tc r. Padding is an r_£.L :-a.:£^"er v ~c": scrlrgl, 

argument ~%hi^h is the redding character desired t rill :rt :he hrffer : :c the 
minimum llol^ "rld^r- c^frrltl^r ^c- hlcJik. 

EXAMPLE 1: 



INCLUDE LIBRARY 
BYTE BUF [8] 
INT MYNUM 

BEGIN 

MYNUM-5 68-11 
INTSTR MYNUM, BUF 

• # • 

PUT NL, BUF 

This will display J 

557 
EXAMPLE 2 1 

INTSTR $FFFE, BUF, 10, 4 

will Install the string " -2" Into BUF. 
NOTE 1 

lo If a minimum field width Is specified, the number will always be right- jus- 
tified In the field* If more characters are required to output the number than 
are specified for the minimum field width, they will be encoded without any 
error Indication. 

2^ To convert an unsigned (BYTE or WORD) variable, use procedure WORDSTR 
instead. To convert a REAL value, use procedure REALSTR instead. 
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PEOC JSE 



USAGE i JSE [Addrs.-r " ^ " L: * /jci ^:^r-i '/ ; [ 

prtyfj&Atixe -JSP. c^lls ?. ™Bchi tie latisu^^e; s-ic-rc-Uwj.ac aw «. ©pcvif^ed address, 
-7 t:L"*r \7 " - 5-; ~r-~'\ 1-** ~ - - . * ocessor ~* *~.rdware registers 

it'. o^c-^Ul^.l lalcr a. th« callc ^ier^Se the address "lie desired 

ruULixie. ,Lrs^ ^..^k- Stl&gs are optional arguments which specify the 

desired values :s _.„s tailed in the A, X, Y, and flags (processor status 
word) registers „ ^-.ertive/ 7 __1L. register arguments should be type BYTE* 
Naturally the address xust type WORD. Ir, is possible to sample rtie values 
returned in the registers from the machine language program. 

Please see Appasid^r: 1 fcr £, detailed explanation and examples of JSE. 

NOTE : 

1. You will need to INCLUDE PROSYS near the beginning t-f yrur program in order 
to use JSR. 



F11C LKNSTR RETURN LENGTH OF STRING 



USAGE : Bytev&r * LHMS1S ■; String) 

LENSTR is a function which returns a BYTE result indicating the length of 
the String which is the argument* 

EXAMPLE 1: 

INCLUDE LIBRARY 

BYTE NAME [20] 
BYTE SIZE 

• • • 

BEGIN 

MOVSTR "Hello", NAME 

• • • 

SIZE=LENSTR(NAME) 

This sets SIZE=5. The size does not include the $00 byte terminator. 
NOTE 2 

1 • You may find frequent need of a statement similar to 1 

1? LENSTR(LINS N > C 

where LINE is an array of bytes holding some string* This can be more 
economically written ast 
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LOAD, UNLO I EXECUTE PROGRAM OR OVERLAY 



USA(,- .jOAD I: i\.~L.= _ -:/c,^ 

r l : ~ ' AD procedure load " : ^ilz^l-^ ^.rd executes ^r^rs^os l.^ys on the 

-rprls II and Commodore 64. is the desired piograis or file .ns^e. 

litflcge is an optional BYTE c :viu'zsv- : lonslstirig if se^eis.I i->Il fl^gs used to 
control the action taker: by ths LOADer . Please sae ns C-hsptsr S if Ice 
PRO^_ - NGU AGE MAir I — - = is and examples. 

NOTE 5 

1. You ^111 read to INCLUDE PROSYS near the start of four program in order to 
use LOAD. 



WUEiz L£sSI4S^ SEARCH A LIST OF STRUGS 



USAGE : Intvar - ;8trlrg, flist :; Hscr : : ?clc [~ Limit]::) 

Function LOOKSTR searches an grr^j of springs, "irylrg rc xaateh e gl^en 
h. :rir.g. String is the desired string ig iry zc ^icch. Ills 4 * is t-ie starting 
dlcrass of e 11= i of pel t: cars to s wrings - zar^ii'ated by g SG000 word. Nstr is 

an optional argumerrc apeeifying che maximum number of scririgs to search. Fold 
is an optional argument ~ "hid If set TRUE, will causs lower case alphabetic 
characters to be cons: f srsd ecrl to their upper cass irrivalents. Il2±t is an 

optional crg^nc specif ring the maximum number of characters co compare within 

each strings lucres' Is returned as -1 if the siring did nc ":. ~£tch, or as the 
array index "rc zhe stilig that did match. 

EXAMPLE 1: 

INCLUDE LIBRARY 

INT 1 

BYTE COMD [20] 

DATA WORD KEYWORDS [ ] = s, M0VE" , "DRAW" , "ERASE" , "DASH" , "REDRAW" , "£XIT :; s 

BEGIN 

MOVSTR "ERAST^COMD 

I-L00KSTR( COMD 3 KEYWORDS ) 

This will return 1=2, because the string in COMD matches the third entry In the 
list. 
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FDHC MAX 



RETUEH THE LARGEST OF TWO OR MORE ?ALUES 



USAGE : Wor - * z z -- ' ~ . < - . - _ 

argume-..--- .:: type MOID 

of two or more addresses 



EXAMPLE li 

INCLUDE LIBRARY 

WORD 1 
WORD J 
WORD K 

BEGIN 

J=1000 
K=$D000 

I=MAX(J,K,$COOO) 

Tnis will return I=3D000. 
NOTE : 

1. Each value to be tested must be explicitly included in the function 
call. You cannon find the Largssz value t.\ an aTTcay by merely calling MAX r 
the array name as an argument. The following example shows how a loop can 
perform this function. 

EXAMPLE 2: 

WORD LARGEST 
WORD MYARRAY[ 100] 

WORD 1 

BEGIN 

LARGEST = ; Dummy to initialize 

FOR I = TO 99 ; Find largest value in array 
LARGEST - MAX (MYARRAY [I ] ? LARGEST) 



: • - . irguments - 
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RETURN THE SMALLEST OF TWO OR MORE fALOES 



USAGE j Wordvar ~ dTi: LI, \ 

Fur.-: - : _ MIN returns the smallest of two or more arguir::: :r \ 
(unsigned) . ~~ :c: :se it ~~I:r trre REAL arguments. .' . is normally used to 
find the less - m or more addresses. 

EXAMPLE 1: 

INCLUDE LIBRARY 

WORD I 

DATA WORD BOUNI ;> 103,200,300,400,500,600 
BEGIX 

1-351 

i-:iii t ;i,boufd;s; ; 

Thir ~;li: return 1^311, because : r - ? 3x2 liar than 400, 



FUNC MLGET LOAD MACHINE LANGUAGE PROGRAM 



USAGE : Wordvar = MLGET (Filename [ : Loadaddress ; } 

Function MLGET loads a machine language program. On Commodore 64 systems 
it is expected tc in standard Commodore format fcr e machine language PRG 
file a For Apple II systems it is expected to be a standard Apple BSAVE type 
file, Jdlssssis la a string containing the desired file name. Loadaddre^s is 

an optional load address If act specified or 0, the load address will be the 
address at x-jhich the program was saved. The function returns a word result 
which will be $0000 if an error occurred, or the address of the last byte 
loaded if successful. 

You may load as many programs as needed by making multiple calls. No 
checks are made to see if trie loaded program conflicts with other memory usage s 
and the memory allocation pointers (L0FREE, HIFREE D etc*) are not adjusted. It 
is your responsibility to insure that an appropriate location Is used. 

Please see Appendix 1 for more Information. 

EXAMPLE 1; 



Copyright (C) 1986 SMA lie 



Rev. C 



BYTE DUMMY 
EE PEAT 

ENDPROG « MLGET (MLPROGNAME ) ; Load Machine Lang, supper- • — - — r.? 

IF ENDPROG = 

} ;? ::i "I^e^^ _r^^ I'.-,.. ■ lie-re--- and close drive door." 

Ill IL . "I „ ^s.: -;,? '-I.e:.... r^ri~ s 

DUMMY = GETC 
UNTIL ENDPRCG - ... 

NOTE : 

1. For Co^s.c-cn"~.~ 5-£ . file names for MLGET must match the desired name exactly 7 . 

Ire! ur ire rrrsr arc lower :ssft and character set selection. 

2« for Ad pie Il ? remember trat many Apple programs load at $2000 before 

r elecrilrg trar,sel ~ss to """sir f :_r_?l destination. In this case you may need a 

BUFFERS HIRES command before loading to help protect PROMAL from being 

overwritten. 

3o You vjill :ieed to INCLUDE PROSYS near the beginning cf your program in order 
to rser MLGET. 

4o For Apple II 5 the default load address is found in cue AUX_TYPE field of 
the directory entry. See the ProDOS Technical Reference Manual for details. 



PROC MOVSTR COPY 01 JOIN STRINGS OR EXTRACT SUBSTRING 



USAGE; MOVSTR FromString , ToString Limit] 

MOVSTR is a procedure which is rssd to copy strings, to concatenate 
strings, or to extract substrings '.lee, 5 replaces the LEFT$, MID$, and RIGHT $ 

functions found in BASIC). fr©«Srriag is the address of the string to copy. 
ToStriffg --.be address cf the destination*. Limit is an optional argument 
specifying the maximum number of characters to copy. 

EXAMPLE 1; 

INCLUDE LIBRARY 

BYTE LINE [81] 
BYTE SAVELINE [81 ] 
BYTE KEYWORD [5] 
... 

BEGIN 

MOVSTR LINE, SAVELINE 
This copies the string LINE to the buffer SAVELINE. 
EXAMPLE 2; 
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MOVSTR " today.", : - INE) 

This concatenate; ^ ' '-?. string literal ' r ~ :,r - ' -\i rr r i ng LIME. 

EXAMPLE 

MOVSTR LINE, KEYWORD, 4 

£ : : * :ic:a.:eri o: -r^ £rr_ \„k LSZ ^rr installs them in 

. . - i ' 1 i...... 5 ...<.r does not include the byte erring 

v .a '". i^rirrg :ray overlap the source string without 

EXAMPLE 4; 

MOVSTR LINE,LI^B-~l 
LINE [0]= 'A' 

This inserts the character "A" at the beginning of the string LINE. 
NOTE; 

1. MOVSTR always installs a C byte terminator at "he ezd of the copied string. 
Therefore you should always allow room for it , 

2. When specifying a particular element cf an array for tire source or 
destination , be sure to include the # operator to indicate the address cf the 
element instead of the value ( e • g o , #BUF [1] is correct) • 



FUNG NUMERIC TEST IF A CHARACTER IS A DIGIT 



USAGE : Bytevar - NUMERIC (Char) 

Function NUMERIC returns TRUE if the argument is an ASCII iruraerjc digit and 
FALSE otherwise. The argument is expected to be type BYTE (net a string!). 

EXAMPLE 1: 

INCLUDE LIBRARY 

WORD VAL 
BYTE CHAR 
BEGIN 

VAL-0 

WHILE NUMERIC (GETC( //CHAR) ) 
VAL= 1 * VAL+( CHAR- ' ' ) 



This accepts a series of keystrokes until a non-digit is entered, and sets VAL 
to the numeric decimal value entered. 
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FUNC OHLIME 



USAGE : Bytevc/r IZlll:! ^ V :_"r : 

or 

Bytev^.: " -1" T£Z . "-"-ii ** tl-„r 

Function 01Ti:::i _r. s :i~" - " : " : 1 ~ j ~ - -'2-- 

and if so, in. — . . . _ ' 

. : : , Sl^; . — — -~- ' ~~ ->^- ~ ~~ - , " : - ' _ "" - - 

. I", ; and ^irsr is ^/ar^; " ; 1:2-=-. :r ^ . - ; - '~* £ " ^; ~- 

receive the volume name. The function returns _ 7.7.1. :t ~~ ~. irivs is 
FALSI :7:-:.erwise (in which case IOERROR holds e icde _ 7:^£.-i::g 7ia i^sc^ £3 
described z ->~ 7~77 f^ctic-, which will ncrnsll': - i fc-r illegal r. - - . : 
for not reaaj, cr ?2E icr ro-v-exisitent) . if the !rrf: araraent is C f then the 
second arer-Ten; ~ - :*r re as a ProDOS uni-- ~ i.:c; »^:L-7.;irea — a 
device IIT ^hier i? e hyte ^: th the following f ::::mat : Bit / is the drive 
-;r^~r hit r '~dr:7/e l - I s drive 2); and hits -^~7 air- ":he slot rrrraher 73-7% 
hits C-3 are The volume name is returned tne specifies baffer as a 
IZSil^L srricg The name will have a leading r ' :r~: e :i"~g " % ersrrrre 

"/uses* disk.' i: = 

EXAMPLE 1: 

INCLUDE LIBRARY 
INCLUDE PROSYS 
• • • 

BYTE VOLNAil [13] ; Buffer for diskette volume name 
WORD HANDLE 

IF ONLINE (6, 2, £17) « have second floppy disk? 

FILE - 7?EN ( : ^.S^HATCH.T" ,"ir j ;Gp<~r. file jr. drive 2 

ELSE 

FILE = OPEN ("1; SCRATCH. T","v:"; 
IF FILE=0 

ABORT "//cCan'fc open SCRATCH. T for writing" 



NOTE j 

1. The /RAM device is normally configured for slot 3 drive 2 and may be tested 
in with ONLINE. 

2- You will need to INCLUDE PROSYS near the front of your program to use 
ONLINE. 



Rev. C 



flic mmm 



OPE! FILE OR DEVICE 



USAGE : 



OPEN is i 
devi " ' 
desirec 
ter (nc 
follow! li- 



re ! ) which 



o o c ~Ms%' 



it tonal an 
■iosen f ■ 



J. o d 



ac- 



R' Read access 

W Write access 

A ' Append (write, beginning at and :f file, aicess 

'B" Both read and irirs '5cn eTsrlsdrls as, Sssscdsre r4 except as noted 

below for use niti "lie i imn: itrnral :r T de~~iaal 



The default access mode ia R" . The remaining optional arguments Xocheck 
and dypa are normally omitte^ : end are used for opening special 
system-dependem file :"pes. These system-dependent options are discussed 

below. 



Inn irritiii returns a nci— ir: fdla dancda vpe WORD if ilia a^an 

was successful; arc " if ia las net, lliis fila hsnaia (also sometimes called a 
file descriptor; should be saved in a WCRD variable. After opening the file, 
you can refer zo the file for I/O operations by simply nsing this handle. The 
handle is required as the firaa argument for other library routines which 
operaae cn files* 

If OPEN returns 0. indicating chat the file rorld noi be opened, then the 
pre-defined variable 10ERR0R indicates the reason, as fellows J 

uearing ( If fraction OPEN returns 2 X 



.ic error- dermal. 
Illegal access mode character . 

Illegal file or device name. 

ranee nc a ready (or vol use net round on Apt Is 11} • 

File not found (for R mode access). 
File already exists (for ¥ mode access). 
Can't open another file {e Q g $ no more disk buffers) e 
Write protected (for A cr W access) « 
Other (system dependent 5 see your computer manual) . 

Yen should always rest for an unsuccessful open. 

EXAMPLE 1: 



I0E5R0R 



3 

4 
5 
6 
7 

8 or aore 
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INCLUDE LIBRARY 



Z 

IF INPUTFILE^O 

ABORT "Car"" ~: en ±nzs'; :: 

WHILE GETL" = Il^Uf FILE, hit r_ 



The example above could be expanded for better error processing as follows; 
EXAMPLE 2; 

INPUTFILE=OPEN( "MYDATA. D" , "R" ) 
IF INPUTFILE=0 ; open error? 

CHOOSE I0ERR01 

3 

PUT NL, "Disk not ready." 

4 

PUT NL,"MYlA,Tn.. 1- fits not found." 
ELSE 

OUTPUT "IC^isic ~r::- -vl" 5 13ERR01 
ABORT "//CProgram aborted." 



1 3 The Commodore 54 firmware limits the maximum number of open files tc three, 
of --hich only one nay be open for writing or appending If using telatrre 

files (see ^ppeadis M) - at most cue sequential file may be open, and DYNODISK 
should be off o DYNODISK uses up one buffer Inside the 1541 drive. 
2o 7c l the Apple Il ? the maximum number of open files Is governed by the 
number of available cnffers (see the BUFFERS command in the PROMAL USER'S 

guile;, o 

3, f or the ripple and Commodore, the file handle point 5 to a data structure 
maintained by PROMAL* The first part of this data structure Is the file name, 

as a PROMAL string* Therefore, If you wish to display the name of a 
successfully opened file. yci> can simply output the file handle, for example: 

PUT NL,"Now reading file INPUTFILE 

4. Devices such as the printer, modem, workspace, etc. are opened in the same 
manner as files . For examples 

EXAMPLE 3; 

WORD P1TR 

PRTR - OPEN ("P'VW') 

IF P1TR - 

PUT NL, "Printer Is not ready." 
ELSE 

PUTF PRTR, NL, "This will be printed « " ,NL 
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4-31 




.> ... ... ^ _ Fo^r.30':~. 1 ?• .Z" : V. 

.:cr£;„n p £ J s t at: 7 -o..r r o Gsr^:..'; 5 r a s 1 o r " :r j. ^ ic • ... :, : a d zc tza z-zl- , 

This allows your PI/d>.7 :r:^LcQ8 to read BA5TT program files, machine language 
^^!. word processor jrl-a, sec. If you specify Nocheck as TRUE, you may 

^ ' cotionai: > :.: ~ z"zz c^;men: Tppa which is an argument of type BYTE 

specifying the type zz: zz±s desired. This argument is system-dependent. 

~rr zzie GogaodoL-g c- 9 ; zz ran be ei;y cf rhe following; 

T Ttdd rpp- idlrr "I ASIC and machine l^rguags files^ 
"S" for. ?1Q type filss 'Sequential files; 

The defrrlt type is "S"o Per sirsnrle: 
C64HANDLE = 0PEK;""1^8IC FLOG" , "R" , TRUE , "P^ ) 
opens a fil* :.3ined "BASIC PP.: d" :f rype ?!T for reading. 
C64HANDLE - OPEN( "WordPr c cTara" : ? TRUE . "-J" ; 

opens r ffde : f pe USE for 



You can also open to rsad a direr ry , oper. £ direct access channel : cr the 
command/error channel. Ths Tyre argument she rid not re specified in this 

case, for example J 

C64DIR = 0PEN("1 TRUE) 

opens the directory on drive 1. Do not attempc to open a directory for 
writing- After opening a directory, the contents read will be the sector 
contents cf ths directory (minus the track and sector links to the next 
sectcr;, * starting with the BAM. Consult Anatomy of the 1541 Disk, by Abacus 
Software 9 for further information on the format of the directory c It is 
reconner.cad that GZ7Bl*KF be used to read the dat&o 

EXAMPLE d "COMMODORE c^p 

WORD C64DA ; Handle for DA file 

BYTE CHAM ; CS4 channel v for DA file 

• • • 

C64DA = OPEN( ,, # M , 'B',TRUE) 

CHAN - (C64DA+LENSTR(C64DA;4-2)3< 
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EXAMPLE . bbbDBQRE 64): 



mel 



C64DYNO=0 ; Disable DYNODISK 
C64CMD = OPEN("%", ^B' , TRUE) 
PUTBLKF C64CMD, FMTCMD , LENSTR(FMTCMD) 
IF GETLF \ C 64CMD , BUF ) 
PUT NL,BUF,NL 

T:Js :iens the Commodore 64 command/error zzzz.z^' zzzzez y '-sues a 

command to format the disk, and displays the -...r uesrsga from cae error 
channel, Internally, PROMAL will use channel li rcr ?ri^e It ;r=r-lce 3) and 14 
for drive i„ levies i., , Zrror messages are Zzzz :zc,z _.~ing GETLF . Commands 

mist be sent using PUTBLKF (not PUTF or 0\JTY.Zz ' - balers sending commands to 
the disk command channel, you should disable bb50BiSKb because the commands you 
send may cause the disk to destroy the special bbWO cede in the disk drive. 
Internally, PROMAL always leaves the commana/aiio-r zr^zdis) open ail the 
time; closing and opening an error channel makes che appropriate "connection" 
through tra handle. 

PROMAL assigns Commodore channel I zz zzz Printer arc ne T device 

; serial port)* The secondary address fcr trie printer c../ . Is a-le-ctc-l . : 
Meeting the variable C64PSA before the ops:, "see Appcrrdrr b Channel 1 is 
reserved for the DIE function- z z, zz are assigned channels _ - ^ld ^ : :~ 
secondary addresses the same ea tre channel. Therefore if yrr wish tc use £ 
channel fcr some special purple a in. z machine language progra^ ~; : u should 
choose a channel bibs 9 . r lb ^ orrid a possibbs .inflict v.. zlzse 
the Commodore command/error channel c Do n^c attempt any direcc serial bus 
acti-ity f rem a machine language program with DYNODISK enable? 

Since DYNODISK uses one extra brffar inside riis 15^1 b f . b_ drive, under some 
circumstances you may be able tc open fe^er files -icr bbFUISK enabled. Under 
no circumstances should £ file be opened with DYNbl„rb azaclzz while any other 
device other than a single disk drive is connected to the serial bus. Failure 
to observe this precaution will probably result in a "hung" system. 
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cons : ;V; * le 


ProDOS 


Technical 







i Manual . For 



AIIHANDLE = OrZN( ,f BA5PRG" , "R" , TRUE) 

opens J:..-, fil^ for reading. BASPRG could he a Basic program f^r *ry 

other type of tile) . 

^-IIHANDLZi - CrEN v i^iTER ' , "W^ , TRUE , $05) 

This 0y3is file LITTIR :. :: cy^e TXT for -rite access. 

fcr r--ppL=. Il s tailing to open a locked f i le for access will be 
treated as a write-protect error. However, opening a locked flip cr write 
protected disk for append mode cannot be detected as an error until an actual 
attempt is made to write the file* Therefore you should always check D10ERR 
after the first write operation in append mode. The f iis PRODOSCALLS . S 
contains examples which show how to lock or unlock a file* 
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a screen. Formats trior- - - 

fed, and how any optional 
erpreted. The special 
■mat string. Field 
chosen from the 11?": 



#nl Output signed decim-l lioe e si:, ght justified nr. - fd^di i -laracters 

wide, with leading blank fill, bispday ?iter deabng "ddacks if 

negative (no "+" if plus} - If i i? — £t:id t us- xiiiiruii field vdcth 

needed to display value. 
#nW Output unsigned decimal word, right Justified In. a rielu n characters 

wi-e^ -1th leading blank fill. If i i-x-iooed- use ii^ui: field uidti 

needed to display value. 
#tiH Output unsigned hex word, righ - -" — ?: n o fislc u oia-aitars -lie 

-:i-h beading b fi^d If i is --iii.ee: use iii'idrr^ fie^d -rati is.: o: 

to display value (no leading z^::sd - 
#nB Out pec i blanks (1 if r, omittei . 

#nS Output abugle characc^r or orrdig- berc justified i o >. fda^i if i 

characters with trailing blank padciig 
#nC Output one ASCII character whose "alue is - ceuiu.a: - dd i d& cooiicer, 

then output the newline character th-iSbdd d*l s SOD) . ->CC is ai^rsc^ 
#nE Output scientific notation REAL using a field cf ri characters -,r: 

uef auios re Id if omit tec; : i .__i^o >- boireei ' ai r 1C 
#n. dR dutpn £ ZZ^d lumber using a field n character- vidn ~ = ;> c feeder 

ulaees sao-nu n must be between 3 and 12, aid d nus^ oe less than 



fir each field desirdrtii n tie ocriug there must be a ccr^e^rnf lit argument 
following the striig Jexcaui for r ib £id InCd The valie :i is octdcrai, aid 
defaults to Z ancepi is :r;3:.. ibc-io the maximum value for i is 253 dp to a 
total of 254 characters ®s~ ? be output by the entire procedure call. Hex output 
will show leading seres: o bier numeric output will note To output the charac- 
ter "#" literally m r ue format soring, use 

For #nl„ #nW, #rd£ ? and #iS field descriptors.- if the o*alue to be output 

will not fit in the specified field v-idth, extra characters will be output 
sufficient: to display" the entire value, dor instance, trying to display the 
value 20000 using" a #3W field descriptor will display all five digits , not just 
3 e However, if fewer digits are needed, blank "padding" will be output to make 
up che dif ferenceo For #n.dR output, remember that you must specify a field 
width wide enough for the sign and the even if you know the answer will be 

cositive (a blank will be displayed). If you try to output a value using #n.dR 
which is too large to be displayed, PROMAL will first try to display the number 
using #nE format instead (with the same n as you specified). Failing that, it 
will print asterisks instead of a value. It is usually a good idea to pick a 
larger value for n than you really think you will need when using #n.dR format 
output. 
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'-"~rr"_""r Vie answr' 8 ^ days.", N 
Th;~ ~ri _ - --j- - ^-^ di splay; 
The ansvi: i ~ ~V: days . 



~ - - - JIN" ,LINE 

ivvrvt 7*c^E*5B y *s" .lineno,line 

- • - tifi^i £ iiiiiage return); 

0014 BEGIN 
EXAMPLE 3; 

INCLUDE LIBRARY 
REAL X 

DATA REAL VI - I^lIJViVVf 
• • • 

x = pi * icCwC, 

output ^:w_:.i- : i-i^i", pi,x 

will display; 

pi- ^ wvi : i c.L-:i8E-K)6 

NOTE : 

ls "fes fcnaat string is always required, szd the number of arguments 

sftfcr tr^e f '•^^^ll^'^F^'^^^^'the -«sber of field descriptors given 

Lb tfes &nast string (excluding 4r,B and #nC). Yeu say not simply OUTPUT 
-"ariasle names without a format string tc display cheir value! 

2e Yu. rr Zy output single characters (type BYTE) as well as strings (type 
"CRD) using the #nS field descriptor. 

— The output fons far REAL output uill display with rounding based on 
digits beyond the displayed field . However same decimal fractions such as .005 
Ere net exactly re^resencable in binary format (so. for example, .005 is really 

00£?99?9?99- Therefore a nil- ef shelly c C0f may be displayed as .00 

Instead of cOl with a #n.2R field specifications 

4, Some useful forms of the #nC field descriptor ares 
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7 „ ;.. a new :-,rriage return) 

• _ : li?; screen and hot. 7~t- cursor 

reverse video 

• . - - , ^ t ~ :-„-\ "averse video 

More L'-.f ~~ 7 I: v...atted output -e --.n in the INTERFACING chapter of 

the PROl'-.l *^_r-"t t :-? 77'tTt The BUDGET 5 I*r j program on the PROMAL disk 
illustr-. 7:r~ -7. :a-. fr matted output f c~?paring tabular output data. 



fL:t 177^777 FORMATTED output to file or device 



US^S7; 7737777 Handle, Formatstring : s it eric o c : 

Procedure G"jTPUTF operates in the same manner as procedure OUTPUT above, 
escec: that t7e ilrai. c-.g^aent muc :i c. file 3andle. if a previously opened 
file or device, which is to receive the output* 

EXAMPLE 1; 

INCLUDE LIBRARY 

• • • 

WORD i 
BEGIN 

• • • 

1=100 

PRTR = OPEN ("P'VW' ) 

OUTPUTF PRTR,"#C#10B#I days.#C", i 

This will output to the printer; 
100 days. 

A carriage return will be written after the line, because of the #C field 
specified at the end of the Formatstring. Note that iz is important to 

remember to send a final CI to the printer, because most printers accumulate 
characters In a buffer until a carriage return Is received * If no final CR Is 
received, the last line will never be printed. 

EXAMPLE 2 1 

WORD OUTFILE ; Output file handle 
REAL NETWORTH ; Total net worth In $ 

0UTFILE=0PEN(CARG[ 1 J ? ; Open specified output file 

IF 0UTFILE=0 

ABORT '7/cUnable to open output file #S'\CARG[1] 

OUTPUTF OUTFILE, "//cYour current net worth = $#8,21", NETWORTH 
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IOTE; 



Z FROQDIT HIT FROM PROJ_ 



USAGE : PROQDIT 

It ore-cure PRC 1111 causes an immedrcte curt ::::cm the PRCrlr..... environment • ?:r 

trc ~ .is computer is reset, re-starting BASIC-. For the Apple II- 

t l l^rlCS "Qui:: .'-.11 is executed as descr i : si in Apple's ProDOS Technical 

Note 3 i , « which "'ill result ir: a prompt for n new path name and complete pref It 

lis next system program to be executed -10MAL does not close any -s 
pricr r: exiting, However, for the Apple rl : PROMAL will restore the /RAM disk 
U3ir..r :re Apple-presecribed method if " -? ~ "isahled on startup. 

EXAMPLE 1: 

INCLUDE PROSYS 

PRO QUIT ; Permanently en it IROMAL 
NOTE : 

Is You will rsad to INCLUDE PROSYS near the beginning of your program in order 
tc rse PROQUIT. 

2. Once you exit PROidcl, it zzcsc za re-booted zz resume. There is no "warm" 
entry point. 



PROG POT OUTPUT CHARACTERS OR STRINGS TO THE SCREEN 



USAGE? ir«J^ icem [ ? cranio c c ] 

PUT is £ procedure for outputting text (including control characters) to 
the di splay o PUT may have one or mors arguments . Each argument may either be 
a single character cr the address cf a string. 

EXAMPLE i 

PUT "Hello, world!", 13 

outputs the string "Hello world 1:1 lowed by a carriage return (13 decimal). 
No carriage return is automatically added before or after the PUT is executed; 
it must he explicitly indi cated • This allows lines of output zo be generated 
using as many separate PUTs as needed* 

EXAMPLE 1: 
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::; : ~_v:~; " or " 



Th^ ,.-1-1 -1-=: 

The answer was Ab .oln or Harold lobbins. 

on a ne . single line. 

MOTE; 

1. PUT tr-c-s any argumsn;: between $00 and $FF inclusive as £ single character 
to be outp all otr-v -alues as a pointer to a string ^rEctsrs to be 

output. Strips mu?t be terminated by a $00 byte. 

2- You may mot use PUT f -isplay the value of numeric values. Use GJTfUT to 
perform this function. 

3. If you wish to output l, £ trin^: i^rting at a particular eleme-z oz sn array 
of byte* -VxTt forget the ~ ccetazcL I for example, £Z^ #?AGE : C,i;,, 
Otherwise, only a single chaiacter will be printec zae reason given in 

note 1 above). . 

4. PUT 12 will clear the screen- PUT $i: : X- o-i:p-^ a in reverse 

video on the Commodore 64. PUT $0F, X, $02 will output X In reverse video on 

the Apple II* r „ . 

= . ^ttt N can be used to change text colors on the Commecc-ie o where d is as 
-.,llcv: S : $05=WHT, $1C=RED. $1E=GRN, $1F-BLU, $81=0RG, $SG«BLK, $95=BRN, 
$96=LIRED S $97=GRY1, $98-GRY2, $99=LTGRN, $9A=LTBLU, $9B=GRY3, $9C=PUR, 

S9E=YSL, $9F=CYN. , ... 

A. Mcre information about PUT is contained in the INTERFACING chapter or rhe 

PR0MA.L LANGUAGE MANUAL. 

PUTBlii? WRITE MEMORY BLOCK TO FILE OR DEVICE 



USAGE: PUTBLEF Handla, *Start, Size 



Procedure PUTBLKF does a block ^rite to a file c~ device. Hands is tee 
file handle of the previously opened file- #Sta?c is the address of the_ 
first byte to be written. Size is the size of the block, to be written, in _ 
bvues- The output will be an exact tastch of the contents cf the memory b,oc.; 
no conversions take place, and no terminators or delimiters are added. is.lKF 
and GETBLKF may be used to save and restore memory images , such as arrays cr 
buffers or complete screens. 



EXAMPLE : 
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BEGIN 



OUXtflLE-OPEr-; 1.3^:: * ;open file name given on command line 

If OUTFILE*0 

ABORT "Car/^: ..\.en file!" 
PUTBLKF OUTFILE, BUFFER, 3jC .save buffer conte~:; 



writes zi.e conter-^f cf :he BUFFER array to tha ii_s specified as the first 
argument on the command line. 



EXAMPLE 2 j 



INCLUDE LIBRARY 

CON REALSZ - 6 ; * hytes for each REi_L -ariEtls 

REAL ELASTICITY ;10G; | Elasticity tnatriz for stress analysis 

WORD TEMPFILE ? Temporary file 

WORD I ; Index to ELASTL^IIY matrix 

• • • 

TEMPFILE=OPEN ( "TEMPFILE .MEM" , 'w' ) 

• • • 

PUTBLKF TEMPFILE, //ELASTICITY [ I ] 5 REALSZ* ( 100-1) ; Save end of matrix 



This saves an exact memory image cf the REAL values ELASTICITY [I] through 
ELASTICITY[99] inclusive to file TEMPFILE o MEM o No conversion to" ASCII takes 
place Uo6o, TEMPFILE .MEH is iot a text file) c 

NOTE : 

ic if you wish, you nay test DIOERR after a PUTBLXr to check for disk errors, 
C^:^RR=0 normally f >disk full (works for W device too) % 3=disk write error. 
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ou.-r'-' :haracters or strings to file or oe.:.- 



Procedure PUTF is simil-r , t; except the . argument l_- - r -il- 

Hand. sviously opened file or device. 

EXAMPLE : 

INCLUDE LIBRARY 
WORD OUTFILE 

DATA WORD FILE -TAXI = "1 :MYFILE.D" 

BYTE LINECBJr yi] 
BYTE LINE [ 31 ; " 

BEGIN 

OUTFILE=OPEN( FILENAME, ) ;File name specified in DATA st&'c. 
• • • 

PUTF OUTF ILE , LINENOBUF , ' ',LINE,NL 

This outputs the spring LINENOBLT , e blank, the string LINE, and a carriage 
return to the output file MYFILE-D on. drive 1. 

NOTES: 

1. See PUT above for more information about valid arguments. 

2. More information on using PUTF to output to files or devices (including the 
printer) is given in Chapter & of ?rhe PROMAL LANGUAGE MANUAL. 

FUNC RANDOM RETURN A RANDOM VALUE OF TYPE WORD 



USAGE: Wo reiver =* [(Seed)] 

Function RANDOM returns a psaudo random number cf type WORD, uniformly 
distributed between 1 and 65535c If the optional non-zero argument Seed, of 
type WORD is specified, it will be used as the seed to generate this and any 

succeeding random numbers • 

EXAMPLE 1: 

INC" -DE LIBRARY 
WCE ~ DIEROLL 

B wIM 

DIEROLL - RANDOM % & + 1 
This sets DIEROLL to a random number between 1 and 6 inclusive. 
NOTE: 
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REAL. 



c^Jl.rUO. CONVERT REAL VALUE TO STRING 



=u^fli^n nl zuf fer, Fieldwidth [, Decplaces] 

rr-re^o: ~ 3.7 -1" -* r sed to convert a REAL numeric value to an ASCII 
soring " c ?rs36i::rg --~lve. r_^-~-:r" : /: : oh- desired value to convert. 

r buffer is obe address of ::oe string to receive the ASCII numeric representa- 
tien- z±slzzz±4,Zz is che o ssired number cf char a o tens to represent the number. 
Decplaces is an ooticioal argument specif Ting the cssired number of decimal 
places to be displayed. If Decplacss is onittee tie number will be converted 
using scientific notation. Fieldwii . : ono Becplnnss should be expressions of 
t ypc *j J.J.L* w ^RD • 

Jisld^ldth must be specified between b and 1^ if 'Jec^i&css is specified 
'for normal output^ or between 7 and ±.t of loeepiaees is not specified -''fcr 
Scientific notation -cutout) if becpl&ees is specified, io roost be less than 
or equal to one field oidoo. toiuns two. This is because one fiel£ width must 
always include rocx for o oigr and the decimal poin: IroeOo- If the sign of 
the value to be pointed i£ - , a blank will be output instead If the sign of 
the value is negative, a ^ill be output immediately r C ohe left of the 
leftmost digit Oith any necessary blank padding) . 

if Decplaces is specified, but the value is too large to fit in the 
specified format, REALS TR will first atoenot to concert toe number in scienti- 
fic notation In one specified field -vldchu if it is still too large, one 
number will not be printed, and the field null be filled *oith asterisks (*) . 

EXAMPLE 1: 

INCLUDE LIBRARY 
REAL COST 
REAL OVERHEAD 
REAL PROFIT 
REAL GROSS 
BYTE BUFFER [10] 
BEGIN 

GROSS=1299„95 

COST=557c44 

OVERHEAD = oI8*GR0SS 

PROF IT=GR0S S -COST -0 VE RKE AD 

• • • 

REALSTR PROFIT 5 BUFFER ? 7 > 2 

• • • 

PUT NL,"0ur profit - 5"' ; BUFFER 
This will display: 

Our profit s $ 508.52 
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XVAL--0. 0000005543 

Yl-S../ 31 '-ii:- 

-/- _ - : _ ° ,. '- 57C C T1 dc~ = r :t exact I7 ' x,r r.^sds, 

- - - .^--c'^— ."IiitIe t: : = r 3 ; r c ,o manipulate the convex;^ ^t'put 

f: % € fcrtnat r?-j. 5a :;r -zai^ls- t-.-e Lining program fragment will 

-:t,z BUFFER with lt--li:.:i t crisis ^ .~r:"- might be used ? program to write 

checks : 

WORD PUNTER ;File handle 
REAL AMOu'wl 

byte bit " : . ; 

WORD 1 

• • • 

PRlNTEE=e?E!! / "P" ,W) 

• • • 

AMOUNTS 

REALSTR £&:> : JS\ I , BUI ; S : i 
1=0 

while iuf;i]-" " 

EUF[I;=^''' 
PUTF PRINTER; " $ ' 3UF 



Trie "Tould print; 
$***887.50 



PEOC REDIRECT REDIRECT INPUT OR OUTPUT 



USAGE i REDIRECT #STDI1 [.Handle] 
- or - 

REDIRECT #STD0UT [ s Handle } 

Procedure REDIRECT is used by advanced programmers to redirect one of the 
tifc standarc I/O paths available in PROMAL: STDIN (standard input) f or STDOUT 

(standard output). Each of these paths is a global variable of type WORD, 
defined in LIBRARY, and is initialized to point by default to the keyboard 
device for input or the screen device for output. Hacrfla is a file handle of a 
previously opened file or device. The REDIRECT procedure sets the standard 
path to point to zhe open file or devices If the Handle argument is not given, 
the default redirection is made back to the keyboard or screen. If ^ the handle 
Is specified, It must be open and must have the appropriate mode (direction) 
for the specified STDxxx (e-g*, you can't redirect STDOUT to the keyboard) e A 
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INCLUDE PROSYS ; Where REDIRECT is defined 
WORD OUTFILE 

OUTFILE=OPEN( "SCREENFILE . T" , ) 
REDIRECT //STDOUT, OUTFILE 
• • • 

PUTF STDOUT f "This will go tc SCREENFILE . T M , cr 

NOTE; 

l ^ You j ±11, need to INCLUDE rZCSYS near the begir ::i:_£, :z your program to use 
R&^IREGl o 

2. This function is used by the EXECUTIVE to redirect input and output. 



FU1C RENAME RENAME A FILE 



USAGE % Byzevsr - ZSESKE (defile, Newfile) 

Function RENAME is csed to change the name of an existing fiieo OMfile is 
a string specifying the old file name, as described for OFENo For the Cghheo- 
dore 64, it may optionally Include a drive prefix and file extension* for che 
Apple II. It nay optionally Include a drive prefix and pathname- I^e^ffis Is a 
second string specifying the desired new name , which must be unique c If the 
drive cr prefix Is specified for Mewfile ? It Is Ignored, and the "drive number 
or prefix for CI£f£Is ivlll be used. It can change the file extension, however. 
The function returns normally or an error code as described for OPEN. 

EXAMPLE 1: 

INCLUDE LIBRARY 
BYTE RENAMERROR 
BEGIN 

RENAMERROR=RENAME ( "TEMP" , CARG [II) 
IF RENAMERROR 

PUT NL, "Attempt to rename TEMPoC to " ,CARG[1]," failed." 

• • • 

NOTE : 

1. For the Commodore 64, a default file extension will be applied unless 
NOFNCHK (Defined In file PROSYS. S) bit 7 is 1 (set to $80)/ If NOFNCHK bit 7 

Is set, non-SEQ files or files with lower ease letters can be renamed. 
Normally, NOFNCHK Is 0, which matches only upper case file names and applies a 
default extension if none is specified. 
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USAGE J SETPOSF Handle, PGiiiiri " isgment] 

7r :.s: rrs 31"? ""7 sets t'~~ -^l* po^'-'r - t"--. t byte 1 r - 

•rl;;^ 11 c : Zanils is ::; ::lr ha- if - i : ^ - i: mi- 

fishily :ti 5. VTLZ ilue r-"--£ = ^3ir2'- it:e , • If tie ii^ira:. file 

zoB±t±ctL is greater than 63525 ^i^i'n then Sagsenc ehc-nli be specified tne 
high crder i "bits if rba ccakpleie 2^ hit file position. The first byte :f ins 
file is byte 0- If the position specified is greater than the current end~of~ 
file 3 then the file vill be positioned to end-of-f ile instead, without any 
c-jror indicative Therefore if yz*z wish to use SETPOSF for implementing a 
randcm^sccess file organization, you snould initialise the file when it is 
created by writing dummy records tc ihe file r.n v il it has reached the desired 
maximum size. 

A coxnim iS8 of SETPOSF is :c r etermine s filch £ size. To do mis ipen the 
desired file, then use SETPOSF to set the file to & position known to be larger 
than eni~cf-hiie. Then use GETPOSF to re^i ihs ilea ent of file position. An 

example for function GETPOSF, above, illustrates a second common use of 
SETPOSF « 

EXAMPLE 1: 

INCLUDE LIBRARY 
COM RECSIZE=80 

BYTE RECORD [RECSIZE-fi] ; Current record contents 

P10C GETRECORD ; File, RecNum 

; Read record # RecNum fro® File into Record 
ARG WORD FILE ; Open file handle 
ARG WORD RECNUM ; Desired record # 
BEGIN 

SETPOSF FILE , RECNUM* REC SIZE 

IF GETBLKF ( FILE , //RECORD , RECS IZE } < RECSiZE 

PUT NL,"***Tried to read beyond end of file on file #S" , FILE 
OUTPUT "#C***Record requested = #W" , RECNUM 
CLOSE FILE 

ABORT "#CFile closed, program terminated." 
END 

The above example shews a routine to read a random record into memory from a 
database file, given the record number and file handle, fcr a file of up to 
64K bytes. 
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SET PATHNAME 



EXAMPL.- . 

INCLUDE LIBRARY 

DATA WORD VOLNAME = "/ACCOUNTS/'* ; Desired volume name 

IF SETPREF IX( VOLNAME ) 

RECEIVE ABLE S 

ELSE 

PUT NL,"CaiTt find VOLUME," disk" 



FUNC STRREAL CONVERT NUMERIC STRING TO REAL VALUE 



USAGE; Bytevariable = STRREAL (Strir^ : ->::iable) 

STRREAL is a function which decodes - c-nver^i; a, s~ri~£ into a numeric 
valus of *:/ps jZ-JL. The id::; i ";: c.rgu.oer:t l£ the oifisss : dasired string. 

The second argument is the addres s of ths MEAL ""arise Is tc rscsi\ r e the value 
represented by the string. The string rsay have. cw _„^ie- of leading LloiA* 
and optionally a leading minus sign - The soooog z^erj szcress the rro^tsr io 
normal notation or scien ~if 02 oe'zeoi 2z '2=foraao! « Centers: cc proceeds until £ 
character is erioi jntered which Cc.:.:;: t legally oao! cf tie number ( soch as 
trailing blani., c:id-of -line, comoia, ouo^ - The fu~ctic~ retards a result of 
type BYTE which 5 s an index to this Splits: ter. A returned value of indicates 
no legal digits were encountered, probably indicating an error condition. 

EXAMPLE : 

INCLUDE LIBRARY 
BYTE LINE; Si] 
REAL VELOCITY 
BYTE INDEX 
• • • 

BEGIN 
GBTL LINE 

I NDE X= S TRREAL ( L INE , //VELOCITY) 

IF VELOCITY < OoO 
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below; 



o . :: i .077 ~"; 

l-iTT- TCC- -e -r^re to rememt s: ~. i ; -: ~h ■' „ i ~" '; ; ~ i~ ':ie 

RiL-i :: eceive the value. 

- 3- -ner--! "repose numeric input routine, INPUTR, is de -h 1 - Chart -:r r 

:z :he PROMAL^ LANGUAGE MANUAL and is provided on disk file '--—--\. 



WWm BTE^Ms CONVERT NUMERIC STUNG TO ITrZ CR INT VALUE 



USAGE; Bytevar = sIRr^ Bering, //Variable [ .Radix [ ,Maxf 161G ] j . 

STR' ; ~^L x& a r junction which decodes ( converts ^ a string into a numeric 

value c STR'^AL zzza v nave two to four argument-? - The required arguments are 
String, tea nesireh string, and #Variafels s chs redress of a WORD or INT 

variable (met ITU er I } to receive the value represented by the s:.:igc 

Mails :s si : r Lici:r.l conversion base defanlrirg to base ~ " : nrh nsrfi&lh ir s: 
optional maximum field width defaulting tz 255 characters c The value to Is 
converted may be signed or unsigned . The string may ha^e any number zf leaemg 
blanks e Conversion proceeds until Maxfield characters are used from the string 
or unci! a character is encountered which cannot legally be a digit in e number 
in the specified or default base. A byte variable is returned as an index to 
zlz±B islixiisr- 

EXAMP1B 1c 

As s'jzs "ha.: rha following program segment inputs the line, " 123, 456" from the 
keybo&._ 1 ^i^lxut the quotes) 1 

INCLUDE LIBRARY 

BYTE LINE [SI] 
WORD XDIST 
WORD YD1ST 

BEGIN 
GETL LINE 

B INDEX = STR"- 7 AL (LIME , //XDIST) 

This will install the value 123 decimal in XDIST and set BINDEX=4. If desired, 
additional statements could determine that the delimiter was and so decode 

any additional values (such as the 456): 

EXAMPLE 2 (continued from Example 1 above); 

IF LINE [B INDEX] , " 

B INDEX= S TRVAL (LINE+BINDEX+1 , #YDIST) 
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would sr.- - IBDF and return BINDE."> : : jecause a maximum field width of 

three chafe, u 3 was specified. Bses ~f coding was specified. Any radix 
between 2 and 36 can be used. 



NOTES : 

1 . Be sure to rememb etecif: 
name to receive the numeric value- 
ins tailed in menu:;?" at whatever a; 



¥ crsratu: lu ;: : :ut rf a U2rr^nl 
If you forget r:^ : :rs value will *re 
Irsss happens _ .: be lu that variable a: 



f c If you wish to input a number of type BYTE , first use STRVAL with a 
-"sstiratiicr type WOR? - anf then copy the lou byte tc the final lestlus tion. 

If you use STRVAL to decode directly to a BYTE variable $ the following byte in 
seaory will also be affected. 

io If you wish to input a nuioe: of type REAL, ^se function STRREAL. 

^ ~ If the function returns (no a is: ts) - the variable is also set to 

5. If frequent numeric input Is anticipated from the keyboard, ycu nay uish 

tc use the following function Cy'hich can be found as file INPUTW.S on a PROMAL 

Ilsk) . uhich displays a specified prompt and returns a WORD value ;yred from 
the keyboard; 



FUNG WORD INPUTW ; Prompt 

; Output PROMPT, accept line of numeric input from keyboard, 
; return the numeric value. 



A1G WORD PROMPT 

WORD TEMP 

BYTE INDEX 

OWN BYTE BUF[: C] 

BEGIN 

REPEAT 

PUT NL, PROMPT 
GETL BUF,10 



Desired prompting message 
Temporary value 
Nursber of dtglcs Input 

for keyboard Input 



; Display prompt 
; Input line 

INDEX=STRVAL( BUF , //TEMP ) ; Convert to numeric value 

IF INDEX=0 ; Invalid entry? 

PUT NLo "Please enter a numeric value . " 
UNTIL INDEX > 
RETURN TEMP 
END 



The following example Illustrates the use of this function; 



WORD ILINE 
WORD MAXLINE 

BEGIN 

ILINE = INPUTW( "What line do you wish to go to? ") 
IF ILINE > MAXLINE 
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FUHC SUBSTR LOCATE SUBSTRING 11 SUING 



USAGE j Bytevar = SPi-n : r-ring, Trystring [,Fold [ ^. . ^ 

T _ tl:~ 1 71 II"" _ ~ , , hi „ ? : _ *_ i g Trystrir : f : ~- "lie pre sen : r : f ~ r_ : - I ar 
~ />:i;3nlus:- lilt 1= - .i _ : -,ional argument defaulting Tiich, 

-~- -be treated as matching upper case 
L^r tar^ _ :>z: n z^'zi:zz^l ..n^unt specifying the last character position in 
IrT^.n, a; ill r^:il j-ar'-,- resulting to LENSTR(Trystring) . For 

ii5la,i_a If l-^r ^ 1 ;:ri fie -2h must occu: starting with th = 'tv^z 
z"r,a:zazze:z zz Irjsirlsg. Zz::zzzjz ±z an optional argument specifying the number of 
characters aa Ikatst^Iag ^rileh nasi match, defaulting to LENSTR(Wantstring) . 
For exanais, if Llsdt^I, than SU35IR will consider a iat^ ^oe if the first 
t^i latteas cf icntstring are f i and in Trystring. The fiaa-iii returns zero if 
no match Iz fcaad, or an Index to the character pirns ont if 1- is found. 

EXAMPLE lr 

INCLUDE LIBRARY 

DATA WORD ASTRING = "PROMISE ME PROI'IaL FOR MY BIRTHDAY" 
DATA WORD WSTRING = "PROMAL" 

BYTE TRY1 
BYTE TRY 2 
BYTE TRY3 
• • • 

TRY1=SUBSTR( WSTRING, ASTRING) 
TRY2=SUBSTR(WSTRING, ASTRING, TRUE ,20,4) 
TRY3=SUBSTR(WSTRING, ASTRING, TRi'E, 10. 

will set TRil tc - 1, TRY 2 to 1, and TRY 5 to Co 



F11C TESTES! - TEST IF k. Oil IS PRESSED 



USAGE j Bytevar = t&3X&£> [<*'Char>] 

Function fSSIZEY rests if a -ey is pressed on the keyboard. If not, it 
returns Q« If a key Is pressed. It Is returned as the value of the function 
and also Is Installed In the optional character address If specified. The 
character is net echoed to the display* The key code returned will be ASCII as 
given in Appenldz Bo Testkey does net display or blink the cursor. 

EXAMPLE is 

INCLUDE LIBRARY 

BEGIN 

REPEAT 

NOTHING 
UNTIL TESTKEY 
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NOTE; 



screen. 



¥WMC TOUPPER CONVERT LOWER CASE CHARACTER TO UPPER CASE 



USAGE : Bytevar - ICTPPKL ; ;>ar) 

TOUPPIt : :; a l^i.tlon which tak-s * single ar~ - r ~ /pe BYTE and 

returns an argument of type BYTE. If the argument is a ic r ~er case letter- the 

returned value 12 ':>e -pper ca-e s: 11™--/ : thei - is~ : argument 12 
returned unchanged. 

EXAMPLE 1: 

INCLUDE LIBRARY 

PUT NL , " Do you wise zc Eoeepc ycur mission? " 
IF TOUPPER(GETC)="Y" : accent "3 " or 'Y' 
TAKEMISSION 



EXAMPLE 2: 

FUNC WORD UPPERSTRING ; String 

; Convert all lowercase chars to uppercase ir: strfng. 

; Return same string, updated in place. 
ARC WORD STRUG ; String to convert to uppercase 

WORD I ; Address of character in scring 

BEGIN 

I=STRING ; Addr of 1st char cf ^tiring 

WHILE 1@< ; Not end of string 

M[I]=TOUPPER(I@<) ; Convert if is lowercase 

I=I-KL ■ ; Address of next char 

RETURN STRING 
END 

NOTE j 

1. The argument for TOUPPER mast be a single character, not a string. 
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:cr --a minimum field width, they will be encode. ~.~J . a;/ error 
indication, i^iaimg is an optional character string argum=nv 7iich is 

the padding character desired t: fill out lie b^ffsr ;: i.e minimum fl = ii 
width, defaulting to blank. 

EXAMPLE 1: 

INCLUDE LIBRARY 
BYTE BUF[8] 
BEGIN 

ADDR«$FFFF-1 

WOR n S TT> A"HT)p t B TT F 

This wii. instil rue smug " irsS^: 3 ' ic:c FJF. 
EXAMPLE 2s 

WORDS TR $3 In 31T, It, "C" 
This will insrcll ~" " ir-r' BUF. 

HOTS j 

1, If you wish to convert a real number, use procedure REALSTR. To convert a 
signed integer, use procedure 3TSTR. 



DELETE FILE 



USAGE; Bytevar - ZJ^rZJl (riienan- ^ilfflag; 

Furccicu 1 AFFILE deletes a ffle >r 07 tl craliy 5 a group of files; e 
Fiieaaae is a scrlug argnraenc specifying the file rc he ielatene For tea 
Commodore 0- , it can haw an optional drive uunher prefix* For the Apple ll f 
it nay have a pathname. The optional argument WiMflsg is a byte value 
defaulting zc "i'ALSE. If TRUE, the Filename argument: can include the wildcard 
characters ? and *. in this case, ail files matching the pattern will be 
deleted. Wildcards are not supported for the Apple ii. The function returns 
if successful and an error number as described for OPEN If not. However, an 
attempt to delete a file which does not exist is not considered to be an error, 
because this Is the way the Commodore ROMs work. if you wish co flag an 
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EXAMPLE % 



INCLUDE LIBRARY 

BYTE ZAPERROR 

BEGIN 

ZAPERROR=ZAPFILE ( CA5.1 : 1 ■ ; 

CHOOSE ZAPERROR 



PUT NL , C ARG . 1 " . " dieted." 

2 

PUT NL , C ARG ■ 1 ; . ' : is not a legal file name . " 

7 

PUT NL , " \c l celecsc. cisk is write-protected. " 

ELSE 

PUT NL, M ::c-. deler:er : srror-." 



NOTES : 

1. For Commode rs $k, if y'ou ^l: to delate s file "liich is not type SEQ 5 does 

not have a file extension, or has any lower case letters, you will have to sst 
the NOFNCHK flag cj S8G (defined in file PR0SY5=5)c 

2. For the Apple 1I 5 setting NOFNCHK- $80 will allow file names with no 
extension or empty s^lcirectories to be deleted. NCFl^GEK is defined ii„ file 
PROS YS . S 
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APPENDIX A 







ctiar • 


rieX 










T»TT TT 

inUjli 


L\J 






- 




SOH 


<~ - 










STX 


£,£, 


t 








ETX 


£.3 










bOI 








~ - 








*3 7 


s 




- 


ACK 


± c 




6c 


\J 1 




BEL 


Z / 






'.. £ 


o 


BS 


2c 


1 A 








HT 








r i. 


i u 


LF 








\ h H 


1 -j 


VT 


23 






OC 


i f\ 


FF 


IC 










CR 








OE 


'1 s 


SO 


23 


t r 
<4t 


• 


C? 


- fr 

_ -f 


SI 


;,37 


l "7 
-i r / 


/ 


™*^ 


1 /I 


DLE 


<- - 

3U 










DC1 


il 


.* 


i. 


L£ 


- 

LC 


DC 2 


O O 

iz 


JU 




"» o 
* J 


T f% 

i.b 


DC3 


3 73) 








20 


DC4 






4 


15 


21 


NAK 


j5 


- < 






z.^ 


SYN 


2t 




6 




23 


ETB 


37 


55 




18 


2^: 


CAN 


38 


56 


8 


19 


25 


EM 


39 


57 


2 


IL 


"9 f% 


SUB 


3 a 


53 




IB 


27 


ESC 




59 




IC 


IB 


FS 


3C 






1 F - 


^ o 


GS 


3v 


61 




- r 


3C 


IS 


3E 


• " 


> 


ir 


31 


US 


3? 


63 





#,3 


6 / 




Z ,7 


99 




44 

A C 
• _/ 


68 

C Q 


TP* 

F 


64 

€ ~ 


^ ^ ~ 




* 6 


70 


"?' 


66 


122 




47 


"T 1 

/ J. 




5/ 




g 


13 


I~2 


11 


63 




2 




73 


T 


;c : 


305 




4A 


"4 


T 


6A 


106 


- 


4B 


7 5 


17" 


SB 


10 7 


k 


4C 


7 6 


_ ' 


5C 


108 


i 


_ 


« 


M 








4S 


73 




65 


■ 




-':? 


-c 





2F 


111 


2, 


50 


80 


p 


7C 


113 






81 


Q 


7 1 


113 


C 


52 


82 


R 


72 


114 


r 


53 


83 


S 


73 


115 






84 


T 


74 


116 


t 


55 


85 


U 


"5 


117 


■ 


56 


86 


V 




IIS 


~; 


z / 


87 


w 


/ / 


11? 


W 


58 


88 


X 


"8 


120 


X 


5? 


89 


Y 


7 9 


131 


y 




90 


z 


7A 


132 


z 


5B 


91 


[ 


T S 


123 


{ 


52 


92 


\ 




124 


1 


22 


93 


1 




725 


} 


5E 


94 






5 




5F 


95 




:F 


127 


DE 



Notes 

I o DC! and LZ3 are also known as X0N and X0FF, respectively. 
2. Its Co^cdore 64 character set ROMs do not support all characters. The 
f clicking replacements are inade : 



$5G (92) \ is replaced by S ^ Found sterling currency symbol) 

S5F (95) _ is replaced by <=» ^Left pointing arrow) 

$60 (96) " is replaced by - (Horizontal bar - net the minus sign) 

$7B (123) { is replaced by - w ;Cross - not the plus sign) 

$7C k I24) ! is replaced by |] (left half checkerboard) 

$7D (125) } is replaced by j (vertical bar) 

$7E (126) ~ is replaced by ffi (checkerboard) 
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SETURMEB -,'r ^^r:vl .'l >" -IV^-I : / • • (HEX) 



Remarks 



row) 



5F 



5F 



06 



5F 



(next to 1 key) 



31 
32 
33 

34 



21 
22 
23 
24 



9? 



81 
95 
96 
97 



BLK 
WHT 
RED 
CYN 



5 % 

o ' • 

7 / ' 

8 / C 



35 

36 
37 
38 

39 



25 
26 
27 
28 
29 



9C 
'.7 
IF 

9E 
12 



98 
99 
9A 
9B 
29 



PUR 
GRN 
BLU 
YEL 

RVS ON 



British currency 1 



30 

22 
2D 
5C 



30 
DB 
DD 
A9 



92 



1C 



30 
A6 

DC 
A8 



RVS OFF 



(pounds star . ) 



CLR HOME 
INST DEL 



13 



93 
94 



93 
94 



Q 
w 

E 
R 

T 



71 

72 

7^ 



51 
57 

52 
54 



l! 

12 
li 



AB 
B3 
Bl 
B2 
A3 



Y 
j 
I 

: 



19 
75 
63 
6? 
70 



59 
55 

4F 
50 



13 

15 
09 

10 



B7 
B8 

A2 
B9 
AF 



@ 
* 

up arrow 
RESTORE 



iO 
2k 
5E 



BA 
CO 
DE 



IE 



A4 
DF 
DE 



A 
S 
D 
F 
G 



61 
73 
64 
66 
67 



41 
53 
44 
46 
47 



01 
13 
04 
06 
07 



BO 
AE 
AC 
BB 
A5 
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lend . >: ^ .vLl - Remarks 



- 6A 4A ?A 15 

" 61 4B 11 Al 

i 6c ' 4c i: is 

3A .- 5B 5B 

3B 5D ID 5D 

3D 3D IF 3D 

— -RN OD 8D — 8D 

Z ' ^ 5A 1A AD 

X 58 13 BD 

C 1 43 13 BC 

V 76 56 16 BE 

B 62 42 11 BF 

N - 61 4E OE AA 

M 5D 4D OD A7 

5 , < 2C 3C — 3C 

- .' ; - 21 3E 3E 

2F 3F — 3F 

CRSR up down 11 91 « 91 

CRSR <- =*> ID 9D — 9D 

fl / fl 65 89 — 89 

fl i-l 86 8A — 8A 

55 fc 87 8B 8B 

88 8C « 8C 



= :^-s 20 20 ' — 20 

RUN STOP 03 83 * 83 



Notes t 

CTRL /RUN STOP aborts program to the PROMAL EXECUTIVE. 

SHIFT/ C= switches mode (upper & lower <— > upper & graphics) • 

Codes shown assume upper & lower case mode. 

Alpha-lock (CTRL -A) affects GETKEY but not TESTKEY codes. 
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ESC 



IB 

31 
32 
33 

34 



IB 

21 
40 
23 
24 



IB 

32 
33 
34 



Apple 

9B 

Bl 
B2 
B3 
B4 



9B 

Al 



-I 
36 

38 
39 



25 
5E 
26 
2A 
28 



35 
IE 
37 
38 
39 



B5 
B6 
B7 
B8 
B9 



A8 



7 J" " 

TAB 



ZD 

3r 



29 

5F 
2B 
7F 
09 



30 
2D 
3D 
7F 
09 



BO 
AD 
BD 
FF 
89 



A9 

DF 
AB 
FF 
89 



Q 
w 

E 
R 
T 



/ / 

65 

72 



01 

57 
45 
52 
54 



05 

12 
14 



Fl 
F7 
E5 
F2 
F4 



D7 

05 
D2 

■:■>-. 



u 

I 
2 

^3 



79 

69 
6? 



59 
55 
49 
4F 
50 



1 2 

15 
OF 



F9 
F5 
E9 
EF 
FO 



D9 

D5 
C9 
CF 
DO 



F 
G 



61 
'■2 
6 A 
66 
67 



41 
53 
44 

46 

47 



CI 
13 
C* 

06 



El 

F3 
E4 
E6 

E7 



CI 
D3 
C4 
C6 
C7 
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i C8 

J 6A 4A OA BA CA 

K 6B 4B OB EB CB 

6C 4C OC EC CC 

3B 3A 3B BB BA 

' I " 27 22 27 A7 A2 

RETURN OD OB OD 8D 8D 

Z 5A 1^ FA DA 

X 7c 58 18 F8 D8 

C 63 43 03 13 G3 

V 7 6 56 ie F6 I;6 

B 62 42 02 E2 C2 

N 6E 4E 'J2 EE CE 

: . 6D 4D OD ED CD 

> / < 2C 3C 2C AC BC 

* / > 2E 3E 2E AE BE 

/ .'" ? 2F 31 2F AF BF 

" / ~ 60 7E 60 EO FE 

<— 08 08 08 88 88 

~ > 15 15 15 95 95 

down arrow OA OA OA 8A 8A 

up arrow OB OB OB 8B 8B 

MOTES: 

Alpha lock (CTRL-A) affects GETKEY but not TESTKEY. 
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APPENDIX C 



*** ERROR: ALREADY LOADED 

You have attempted to GFI -r rogram which is already in memory* 

this is delib?-*?'*-^ :iNLO~.~ **--e progr- ~ : "r and then re-issue the JET 

command • 

*** ERROR J DEVICE NOT READY 

U&vxc-2j/,~ rhis Irdi^rrH rha ; hre disk cri'^ deer is rat closed. Also 
cheek for a Ilscmrec zed rff-llne printer or disk drive, unformatted 
disk, e':.e - Cr. the i-rrple II. rhls error prcbally indicates that you 
channel fiskaicea f '*i_hocL Issrhrg a IIIIIi; icrjnand to select the new 
volurr-e (PREFIX * can fix this)- 

*** ERRORS DISK ERROR 

Thl€ icommon error resrags rrdirstcs a hardware read or write error on 
the Ilsk. Check for a disk Iri-'s ;crted off or net connected, etc. It 
may indicate that your diskarte has become damaged or that the disk 
dri ;s heads need to he cleanse c I - nay also indicate that par; cf "rnt 
operating system has beers wiped o;>» in memory by an errant program cr 
similar difficulties c I" say else Indicate an attempt to append a 
write-pro tec ted disk cr locked file* 

*** ERROR % FILE DOES MOT EXIST 

Ycr hava Issued a command to the EXECUTIVE c: act cr. a file ^hirh Ires 
net alii st on ths currently selected disk- P.ensmber that the default 
file extension Is 9 hC s h If you are trying cc act on a file ^hich does 
nor. ha~~e a file extension remember to enclose the narte in quotes ^case 
sensitive or ths Commodore 64) . For trie Commodore 64 COPY command If 
trie file Is not type Str^ the type must be specified alcer & cornea 
Inside the quotes, for example "BASICPRCG/f \ Ir the hippie 11, you say 
have switched llsics -jithout a PREFIX * command. 



*** ERROR i FILE ALREADY EXISTS 

You have Issued an EXECUTIVE command which tried to write a new file 
with the same name as an existing file. If this was deliberate, DELETE 
the existing file and try again o Remember that the default file 
extension is »Co For file names vittiout extensions, the name should be 
enclosed in quotes. 

*** ERROR : ILLEGAL COMMAND SYNTAX 

You have Issued an EXECUTIVE command with arguments which do not 
conform to the requirements o Consult the PROMAL USER'S GUIDE for the 
proper command syntax. 
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r - v: : ?y- ; . il: : -:i -i t :i^ 



*** Ei":/:; :\_ "£'-.: mi! ^ili:~~i r 

: ~r r rrr^ - f _ • :"es to out — - i input-only 



^** ERROR: NOT ENOUGH FREE DISK 

You have issued an EXECUTIVE command which, has tried to write a file to 

disk larger than the remaining disk space 9 c-r . there are no more free 
buffers 'Apple 11) or channels (Commodore 64) available. 

*** ERROR J NOT IMP. 

The command you have issued is not implemented on your version of 
PROMAL. 



*** ERRORS WRITE PROTECTED 

You have issued e cossaanc" v hleh attempted to write or alter a 
rjrite-protected disk (or a locked file on the Apple), if you wish, 
re:no"-s the T "rits protect erichar or UNLOCK the file and try again. 

*** RUNTIME ERRORS DI7IDE 

Division (or %) by zero, or an arithmetic overflow has occurred, if 
this error occurred daring compilation , then a REAL literal number was 
specified which was out of range. The largest REAL number is 
approximately lE-f27e 

*** RUNTIME ERRORS 1-0 ILLEGAL DIRECTION 

A library routine was celled co input or out pur tc a tile cr ds "ice 

-/hi eh was opened in e different modes for example, trying to input from 
the printer* 

*** RUNTIME ERROR: ILLEGAL / UNCFEN FILE HANDLE 

A library routine expected to find an open file handle fcr the firs" 
argument, but did nor find one = Check for a missing file handle iraere 
required. Check to make sure you have properly opened the file or 
device and have saved rhe file handle In e WORD type variable o Make 
sure you have not already closed rhe handle c An OPEN function call 
should always be tested for success. if the function returns f It was 
not successful. 



*** RUNTIME ERROR : ILLEGAL # ARCS - LIB. CALL 

A library PROC cr FUNC or machine language routine was called with an 
invalid number of arguments. Check the LIBRARY MANUAL for the correct 
arguments required * 

*** RUNTIME ERROR 2 ILLEGAL ARG 9 LIB* CALL 

A library routine was called with an Invalid or out-of -range argument. 
Make sure you are using the appropriate type arguments (e«go s not using 
a REAL where a WORD is expected). Check the LIBRARY MANUAL for 
restrictions on arguments* 
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*** 




*** RUNTIME ERROR: ILLEG. " - IODE 




using a value uaere a,... address is required,, et^- If rnis error occurs 
during compilation r you have ^c:3:*p:=s t_- cou^ila £ prcgrau using lErdt 

data after executing a NOREAL command. 



*** RUNTIME ERROR: M/L BREAK 

A machine language BRK ($00) instruction has been executed * If rhis is 
not expected r it is often a symptoir cf a ~lec^ cf c program (;r o^cl" 
the P10MAL library) having been zeroed by an errant program* 1c i&v 

also reflect an erroneous definition ~ : on EXTernal routine or failure 
to load a required 0: dc^are package. 



*** RUNTIME ERROR J 2R3I'L%~L hBD^Z 

A PROMAL PrGGRAld Cpossioly the EDITor or EXECUTIVE) has encountered a 

$00 instruction at the indicated address « This usually indicates that 
an program bug has caused part of the program to become zeroed out. 
Check for bad pointers, arrays out of bounds, using a value where an 
address is required, etc- 

*** RUNTIME ERROR; lEQ'T P^OalulU Mil ICnrEu 

A required soft"* ate package is nor in mercery - Chech to sea :.i you are 
trying to use Rrh-xl arithmetic after a r«uRZuL c^rcnand r It nsy also 
reflect £ defecting ~>u>:\^sl Cellars tlon « If this error occurs during 
compilation, you are 'crying ;:o conpi^e Rual- car, a arcer a l J d?iLAh 
c ommand • 



*** RUNTIME ERROR; STACK ERROR 

The stack has overflowed. This map indicate that you have a routine 
which calls itself indefinitely or a recursion error. It may also 
indicate subroutines nested too deeply or with too many arguments 
passed. If this error occurred during compilation, you hs^a a 
statement with an expression ~rhich is too complex to compile due to 
stack limitations 'for exanpie- 12 levels of parentheses; «> This may be 
aggravated by having many levels of indentation s and by using function 
calls in the expression. In chia case, use intermediate temporary 
variables for sub-expressions to reduce the eonplanity cf the 
statement. 
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ERROR 1: 




L'~r~: C"T~ l r :..0"c':\ : \. ~-_ ' ^ U>: T T It L . / - ; r: ' 

ERROR 2; 

Illegal character constant 

A character constant must be a single character enclosed by single 
quotes "Lack for missing quote or more than one character. The 

quote character Itself, can be written as . 

ERROR 3s 

Illegal string constant 

~- etcing constant must be enclosed on both ends by double quotes (")» 
It may not cross a line boundary. Check for unbalanced quotes . The 
r CCD Is quote character can be written inside a string as 

ERROR 4: 

PROGRAM or OVERLAY expec 

Your program muse start with a PROGRAM statement (or OVERLAY 
statement). Male 3 you are compiling the right file. 

ERROR 5 i 
<Name> expected 

The compiler expected to find an identifier (name' at chis point in the 
statement* Make sure you are not trying to use a reserved word as a 
name. 

ER5LCR c% 

Duplicate name 

The identifier has already been declared previously - Make sure you are 
not trying to define a name that is already defined in the LIBRARY, 
INCLUDE file, etc. Also make sure that you don't have a variable tha ': 
duplicates a procedure, function or data name, or visa-versa c In scae 
circumstances , this error may refer to an identifier on the line above 
the one shown. 

ERROR 7: 

= expected 

The compiler expected to see an operator at this point in the 
statement. Make sure that you are not trying to use a simple 
(tin-subscripted) variable as an array, or as a procedure name, 

ERROR 8s 

Constant expected 

The compiler expected to see a constant at this point in the 
statement . Be sure you are not trying to use a variable name where a 
constant is required. Remember that you may not have constants of type 
REAL. Also check to make sure that the value specified for the 
constant is not out of range (Notei the offending constant may be 
slightly beyond the row of asterisks on the compiler error message). 
For example 5 $100000 is an out of range constant • 
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ERROR 9; 

] expected 

The compiler expec 
statement* Rememb 
delink: TaOMAL arr:; 
that you should nor '7-" 

ERRQh 1.; 

Illegal h~ *~ " ■ r 



f\j J.UL 



to 



heean?e the resrlt Is 



rCiv-s tat ardent index sust he a srxrl_e rarratl 



no 



i r 



68 Ot 



a "JHCOSU star siren t taust :;:r:r:eh 



following ~he CHQCSh ssactlj 



)nstc 



~vo: 



5 c r SUSHI c t na r £ 

*~7p^ ^'W'S.^e _ .".3 

7^ -y^e of the stress 2 en 

- type cs.se to nalcs a szi&j 
a~iacle~ for cXciLilc 1 . h - 



2nd he 7 not be type EttALe Finally keep in mind that the boolean 
1 r-e r?tc?? £.* T D . OF . 7:^ T , a re ZOP c ^era c e n^ 7 t vne LYTE * 



ERRCh lis 

Illegal subscript 

Subscripted variables may not be rises for local variables or arguments. 
ERROR 12s 

Variable name expec tad 

The compiler expected tc find a variable name at this point in the 
statement o Make sure that you are not trying to use a reserved word, 
procedure f function name, or constant for a variable. DATA names may 
net be the destination for an assignment ^tstsxent. 

ERROR 13i 
) expected 

The compiler expected a right parentheses a?- "his point ir the 
statement. Check for too many or too few arg-jmenrs on a function call, 
or missing or unbalanced parentheses « Also make sure yon are not 
trying to enclose the argument list for a procedure call in 
parentheses » 



ERROR 14s 

Illegal expression 

The expression does not fellow the syntax diagram in Appendix P of the 
PROMAL LANGUAGE MANUAL, Check for an illegal sequence of operators, 
missing punctuation. etc = Note tha t the indirect operators (S< 5 @+ f 
@-, @ . ) may not appear after the variable name for an assignment 
statement (use the global array M instead). 

ERROR 15s 

# is illegal here 

The # address operator cannot be used here. The address operator 
cannot appear on the left hand side of an assignment statement 9 nor can 

it be applied to anything except a variable. The # operator must 
directly precede the variable name. 
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. = expected 

^c>~- .-1 _ c pec ted to ssf lift 1:=^ ' / \\ r.-_ . v. _^ 
tn " -~ _.r . -av;_~ , The type ir-r^-, _ ^c* z ; ^ i -: ~ ~ ~- t:n -*~rr i-j - 
function name. 



erro: 1 ; 




this is c general error message Indicaring that the compiler could ret 
constrrct e legal stsrsssrt vjith i"hct yor ha^e at -this poin~ in the 
lire* Check, for i tro zi&ry Ersr^Sirts rr a procedure call.. ? rt r: rts 
a siiEpia variable, stec Also be sure you didn^t forger the 90 rhich 
must precede a comment* 

ERROR 19 s 

, expected 

The compiler expected a conn. 5 st this point in the statement. Check 
for too few subscripts on an array reference, or too few arguments on a 
function or procedure call. 

ERROR 20 i 

Illegal type name here 

The type (BYTE, INT, wORD c or REAL) indicated is inconsistent ^ith 
prior usage. 

ERROR 21? 

Net in 1HILE or REPEAT loop 

The BREAK or HE XT 1 .^?tements may only he used inside a WHILE or REPEAT 
loop. 

ERROR 22 % 

Statement expected 

This is a general error Message indicating that the compiler was 
expecting an executable statement but did not find one. Check for a 
missing END statement in a prior procedure or function or a displaced 
declaration^ 



ERROR 23: 

Wrong # of arguments 

The procedure or function call has too many or too few arguments. 

ERROR 24; 

Indentation error 

The statement stares with the wrong indentation** Each level of 
indentation must be exactly two blanks. A statement following a 
conditional statement must be indented • If this is a statement 
terminating a conditional block such as an ELSE or UNTIL, it should 
not he indented as far as the line immediately above it« Each choice 
of a CHOOSE statement should be at the same level of indentation as the 
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by an UNTIL at the same 



ERROR 26s 

Unexpected - ^1: ilir 

The s^^yl^'r en; cl -file without having reached the END 

stETSxsri in the its ±7i program. Check for a missing E1D statement or 
1ECLU l E s „ a r £:» er:t - 



ERRC2 27: 
Unde: c r r- ; 

The identifier i nr:icc :sc .'as not been previous.;" declared or defined • 
All v~r:&ble&- ^ l.^': iz^: - - jjxiLii^a a: 5 functions must be declared 
before they are referenced- thsek for a missing INCLUDE LIBRARY or 

other l>iir r S *tsr isr.srr ^ ' ': r r zzzi . irg error. 



ERROR 28; 

Illegal FOR variable 

The index "/aria for e FOR-loop must be a simple (non-subscripted) 
variable cf cjv-e T J ORD . 

ERROR 29; 
TO expected 

The compiler expects ...... e keyword TO to appear at this point in the FOR 

statement. 



ERROR 30 i 
I expected 

The compiler expected to find a jlBzz or acker £..r ..-.is ^il;. 5'^-er.L^r 
that sq~jsra brackets , not parentheses, are used to delinir Ik^r^l 

arrays Make sure you are net trying to use an array nsse the lef^ 
side <~-f €,r assignment statement without specifying which eler,e :z ~ J ir? 

array should get the result. 

ERROR 31 i 

PROC or FUNC expected 

The compiler expected to see the keyword PROC or FUNC Et this pcint in 

the declaration. This error can also be caused by a missing type 
indicator (BYTE, INT, or WORD) or an EXTernal variable declaration. 

ERROR 32 i 
AT expected 

The COMPILER expected to find the keyword AT at this point in the 
declaration. 



ERROR 33 j 
Illegal refuge 

The keyword REFUGE must be followed by a constant of value C% I s ci 2, 
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EEROR 34: 

Illegal REAL constant 



.1 expected 



\vi of s 



taxation 



ERROR 36s 

Illegal import 

You have more IMPORT files than are allowed (maximum 1 . 
erroneous declaration in an iuipui L ed block- 



r have an 



ERROR o; : 

Illegal <import var) i? - 

You may not use the high-byte operates v ? ^ ✓ or. an imported variable 
appearing on the left hand side of an assignment statement. 

ERROR 38; 
Illegal export 

The declaration cannot be EXPORTed • Only constants , variables, data, 

procedures and functions can be EXPORTed. You may not EXPORT EXTernal 
declarations. Check for missing EXPORT keyword on PROGRAM line. 

ERROR 39; 

Too many dimensions 

PROMAL arrays may have a maximum of eight dimensions. 

ERROR 40; 

Demo compiler can't IMPORT/ EXPORT 

The compiler on the PROMAL DEMO diskette does r..c ; support EXPORT 
declarations or INCLUDE filas of IMPORTS. You uiust use the full 
compiler for these features . 

ERROR 12^ s 

Compilation cancelled 

This is not an error message, but indicates that compilation was 
terminated by the operator in response to a prompt. 

ERROR 130; 

lot enough free memory 

The COMPILER cannot find enough free memory for its tables. UNLOAD 
some programs and try again. On the Commodors-34 asing the standard 
compiler, you will not be able to compile unless the workspace is 
clear (cut you can with the demo compiler} c On the Apple 11, if yon 
have issued a BUFFERS HIRES, yon will need to give a BUFFERS 3 command 
before compiling. 
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ERROR 131: 




ERRO?. 1^3% 

Canrc - open list file 

The compiler could not open the listing rile for rriting. Check for 
:-e~:ice r. ready, write-pro tec ted lv;h : Ji-h ... ^11, etc. The default 

extension for the list f lis is "«L"'% 



ERROR likt 

Cam:: '_. : en export file 

The compiler could not open the expo:: file f -z writing. Make sure 
"hat the disk is not write-pro tec ted or full (or the c il,.e leaked on the 

Apple). The Commodore 64 may r_ z ha able to open rhe export file if 
you have a listing enable •. re to limitations cf the 15-L rrive) . 

ERROR 135 J 

Cannot open include file 

The compiler cannot find or cannot open the specified INCLUDE fils for 
reading. Make sure the desire! file is present on the disk. "The 
default file extension is " .S"„ C-n the Apple 11 : this may be caused hy 
not having the proper prefix (volume name) . Aisc f you may have to 
increase the number cf buffers : the Apple if you nave a listing file, 
expor: file, and/or - rated INCLUDE files. 

ERROR 136s 

No source fi la~ Workspace empty 

No source file name was specif ^.-d on the COMPILE command, and the 
Workspace is empty. You need to specify a filename to be compiled. 

ERROR 137? 

Illegal COMPILE argument 

The COMPILE command has an illegal argument. See the P10MAL USER'S 
GUIDE for the correct command syntax. 

ERRCR 138; 

File name duplicates another argument 

One of the output file names specified cn the COMMAND line is the same 
as one of the input files, including the extension. 

ERROR 139 : 

Can't write to L device 

The L device was specified as an output file for the compiler. This is 
not permitted. 
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-Ite to Workspace 

The W device was 
not permitted. 



ERROR 141: 




ERROR 142s 

Forward Reference overflow 

The forward reference table used by the compiler has overflowed* 
UNLOAD all programs and use the B option on the COMPILE command. if 
yon have already done this, use the B=Solf optic-- -? in-rease the size 
of zae forward ref eren: 3 rebls* 



ERROli 

Obje 



: t :ffv: o'"^:::lc*7 (Usa B option) 

Zhs liffer used internal! ' ': 7 the compiler has overflowed, 

in : L2- ai , urograms and use the B option on the COMPILE command . 



ERR01 ; 
Symbol. 



The internal symbol table used by the compiler has overf lowed « UNLOAD 
all programs and use the B option on the COMPILE command • it yon have 
already done this, use the B=Solf option to increase the size cf tne 

symbol table* 

ERROR 145s 
Too many ELSEs 

Your program has an IF with more ELSEs than the compiler can handle, or 
nested loops greater tha' ■ 2an handle. 

ERROR 146; 

Too many nested loops 

Your program has loops nested to a greater depth or complexity than the 
compiler can handle . 

ERROR 147; 

INCLUDES overnested 

Yon have an INCLUDE statement inside an INCLUDE file, which requires 

opening more files than the Commodore 64 disk or Apple ProDOS will 
allow. 



ERROR 148s 

Unbalanced ? (conditional coup.) 

Yon have a ? in column I cf a statement initiating a conditional block 
which is not balanced by a matching ? terminating the conditional 
compilation block. Conditional compilation blocks may net be nested* 
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ERROR 149; 



ERROR 150; 

B option not in Demo compiler 

The B compiler optirn re supports- In -~ the PROMAL DEMO COMPILER. 

You must u.^- cV f u ! 2 .cmpiler (on the System Di— c "o u,- e B 

option. 

ERROL "1; 

Demo compiler line licit exceeded 

The Demo compiler can only compile files with up to 400 Unas 9 
excluding comments (but including the LIBRARY). You need to use the 
full compiler on the PROMAL system disk. 

ERROR 152; 

Disk write error 

The compiler encountered a disk error while writing a file* 

ERROR 153s 
Disk full 

There was ncr enough room to write the f lis r. the disk. 

xxxx ISN'T A TEXT FILE 

You have cried tc s file named xxxx ^hieh the EDITor thinks is not 

a ::ext file 3 Check tc see if yea are trying tc adit a compiled program 
or data* It say also indicate that the file has lines longer than 125 
claiaciers- 7cr the --ppl s 11 r Lz zlbj indlzaze that the file was 
prepared ivtth b ~cri processor Tvh ich sets bit 1 of each character to 

1, " If this is the case, yeu can fix zhe file by using the CLEARS IT 7 
demo program • 

NO BUFFER SPACE 

The EDITor could not find enough free space for lis buffer. To correct 
this, type UNLOAD (and WS if you are not using the Workspace on the 

Commodore 64) s and try again. 

NOT A PROMAL OBJECT FILE : xxxx 

You have attempted to execute a file which is not a compiled PROMAL 
program or a relocatable machine language program. All PROMAL programs 
must be successfully compiled before they can be executed . This error 
usually occurs when you try to execute a program which was compiled 
using the B option but had compilation errors . it can also occur if 
you attempt to execute a version 2«0 module on a version 1 . X PROMAL 
system* 

NOT ENOUGH FREE MEMORY 

The specified program or overlay could not be loaded because there is 
not enough free memory. if it is a program on the Commodore 64% you 
will need to set the Workspace size to and try again o if ic is an 

overlay, you need to unload all programs and restart tne main program. 
If the problem persists, your program may simply be too large* 
Consider modifying it to use overlays, or, use the NOREAL command if 
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J£RRO. 




lead the rsjeeree module € eetoeisrically ^ If the prcgraei r.aris she™ ee 
the as the orcgrair yeu are tryisg re execute. ~;ec rae^e le izc 

enough free memory to relocate your program after leading ite Yeu read 

co unload other programs or free up additional memory as described 
above. 



OK TO CLEAR relullieCl 'Y, :') ? 

This Oeiiscdcie t- message is not an error message but a warning > 1..: Is 
giver rr you spec: feed the B option on the compiler, but there 5 
some eh erg fee "ha v orkspace. If you reply o T ltr $ Y : rue compiler veil 
clear eae rxrRspace and proceed. Other*' else,, 1: rill abort* 

PROGRAM 01 OVERLAY NOT FOUND 1 xxxx 

You have issued an EXECUTIVE command which is uoc a built in command, 
nor is it in memory or 011 disk* Check, for spelling errors , and make 
sure you have the correct diskette. Remember that " C C" will be the 
default file extension. For the Apple XI S you nay have changed disks 
without using the PREFIX command to set the new vrl_ne name. 

xxxx TOO LARGE TO EDIT 

The specified file naee 5 ns;e is too large to EDIT in the available 
memory space. To correct this, t;-pa UNLOAD to free additional memory 
and try again. If you are ecc using ehe Workspace «^r„ tee ^oi^incdoe s t <4 , 
you should also issue a FS 1 coiemano. . :f you hare already dene ail 
this, your file may be tec large to EE1T = Ye^. can split it ir.ee rue 
files using the SPLIT Utile rpu sx<6 ehau edit each file separately „ 

USER BREAK 

This is net necessarily an indication of an error, but shows that the 
program was aborted by the user (by CTRL -STOP on the Commodore 64 or by 
CTRL-C or CTRL-RESET 011 the Apple) • 
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APPENDIX D 



..,.'^-._^J.- hr-ihl^ iIjL-JJS AND z^l^^Ll fh rhh£:ii 

The PROMAL nucl e_.- -lie- h- - 2 i"'"-" many errors such as 

;i vision by zero, cle^L srgrr-rrr r; hiire:;~ „~utines, etc. A typical 
runtime error mess-p. ----If : - 

*** runtime ER?--;r. t~:i - t: 

AT |72B2 

Trrs :elis yon thai yen acrranpt^i tc .a._.:. u 
tec fs7 arguments* Luc "vhere in your prograu uff . 
address is gi<ar lr the arrcr xessage as $72Et. 7: 
men: in your 2isti~£- r . eceei as follows: 

le Execute a, ccirnauc f :.c-n the EXECUTIVE . 

1- Icc^te ;;vrr rrccr-^ sorting address - g = "AT 7 100") :'n t^s "hr? 
i is play - 

3, SuhCracr tils ^l^a using hex ^rihrreri^ free: hue aeireis iispl?y-d 
with the error message. The result is the relative adaress iron the srart 
of your program, for example $72B2 - $7100 = $01B2. 

4 C Using your progisrn listing, find the st^cenent (net a variable eats 
declaration) with an address (shown in the column to the left cf che 
statement) chat spans the calculated scdresse This statement (or ccssirlr- 
the preceding er next statement) is the one -'here your error occurred « 

You can use a similar technique to DUMP the value cf shared global varia- 
bles and global scalar variables (but not local variables) < Shared global 
variables are arrays cf any type, or REAL variables (both simple and arrays). 
Global scalar variables are non-array BYTE, INT and WORD variables which are 
net declared inside a PROC or FUNC. 

To locate a global scalar variable, add the address shown to the left of 
the variable's declaration on the listing to the address shown as the starting 
address for variables in your map display. For example, if your listing shows 



_ 5 - v i ';; r : ~_ many o r 
his occr:: c The absolute 
find the cf rending state- 



8 BYTE MYVAL 

and the MAP for yo^r leaded program shows: 

MYPROG (PR3c ?; 3 '35 CHKSUM 4B9D 

AT 7100-73FF (l^ZSs A100-A2FF) 

then add $08 to $A100 S giving $AlC8o This is the absolute address cf your 
variable, MYAL = $A108o Note that if the variables start at an address above 
the "SYSTEM SPACE" location on the Apple II, you will not be able to DUMP the 
correct value of your variable because the EXECUTIVE has re-used that address 
space* 
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MYPROG ?!0. r : "i; -1,2 

CODE $20BA, GLOB VARS $01C0, $09 



then your pr ~ ?r.an *\i : £ 1- ': "r-p - t - - L. - - s-'-' . ~f f : v - — - : _ - z \~ 

address show . : - - r v r r_r r rd:n" . - -~ -lr : :d~i 

starting addr-=f £ „f T£rl~d:l~' r;r rl r _rr; :rrr~r£ 7:i . n«:n~ 

the above ex^sf-.f. if If €ting sires: 

6 A WORD VALUES 

then the absolute address :i "111111 ~ Z ] Is nt U173 ($:,, . 309 +$A100) . 

When displaying is.e value of "arialleb . ^.member that WORD and INT vari- 
ables are stored wirL „he low order byes il: bc and the high order byte at the 
next higher address. 

~" r*v t eac:*- in the following format i 



Adc : r o -K} a ~f2 -vC -rd -r5 

This f :rnat Is based or -re 1311 standard single precision data format, but 
r- exre-aad v-itb 2 additional tytes in the let- order mantissa t3 increase the 
accuracy rrcm 6 ta 11 signif leant decinal digits o It uses a binary 

rsorssenrarrct: "here* 



o - „ sign ^ -regan^a ^arne; 

2xn = t bit exponent (biased "by $7I\ 

Earr: 55£ s 33 bij nartissa ncmaliged baleen 1,0 and 1*3. 

with an implied 1 bic £ binary point to left of mantissa. 



If you are not familiar vritn floating point representations 9 you may wish 
to consult an element ary :: book cn computer arithmetic, or the IEEE Floating 

Point Standard before attempting to interpret the "alue. 

Heta for numerical analysts? the ?RGi v iaL f Ids ring point routines do not 
support gradual underflow. Any number with an exponent of sere is considered 
zero. Also, rounding-to-even is not supported (but rounding is}. This is of 
no consequence to normal users. 
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mmmw ~ tort 




'Izzzzwzz :cz uric, tar zzZ:azz;zi:Z zz 
■ZZ.ZZS of tne "secondary address = - 
control jour printers 



,_.e si . rd secondary address . . ef auu ~ 
Bit ?=i~£iip case de f aul t = $ 80=y e s ) 
d-d- printer device # .'default 4) 

Y — cbculd sec these -arables the ie=ired r*~~ ira^ ceirre dPZrinr rhe ? 
deuirs^ the 35-:? jL uariable concrete ~*diether or nor Ir^er case an-i upper zczz 
alphabetic characters sdcuid is reveised defers output to the princes This is 
norxsll 17 reeded because rddudtdl .,?cs staucarc *r*c^--_ cnarao~ars m ^cs » 
Conzncdci e-~conpacibla printers expect "Corocdore ASCII 8 " o if your printer 
prints alphabetic characters in the wrong case, ycu can use a SET Df4 command 
from the EXECUTIVE , or in your BOOTSCRIPT. J fileo 

The standard Commodore device number for the printer is 4c However, ii^ >ou 
have a second printer on the serial bus or are using a fleeter e ycu uap ru,sh t: 
open the P device to a different device number c Ycu car. do this by installing 
the desired device number in the byte at $0DF5 (C64PDV) . 

The Commodore 1525 printer dees not supper r fern feeds . sc listings will ret 
be properly paginated, bur Idle printers will ur<rc properly. 

It has been reported that some versions of tlie Coined ere 1526 printer have 
intermittent problems when used with the 1541 disk drive. These problems are 
characterized by a serial bus "lockup", which may cause the system to hang 
inexplicably or to display error number 40 or 41. 3iig problem has nothing to 
do with PROMAL and will also appear with other software, lather, this is a 
problem with the Commodore ROMs ir, the printer and/or disk drive. If you 
experience these problems , you may want to contact Commodore dealer and request 
that he upgrade your system zo zhe latest level ROMs. If in doubt, you can 
find out what ROMs you have in your printer by performing the 1526 self-test. 
If the prints "CBM COMMODORE 1526/MPM-802 PRINTER - REV 07C°", then you have the 
latest orinter ROMs « At the time of publication of this manual, our best 
inforr : cicn is that the latest ROMs are as fellows: 

1541 Disk Drive ROM part number 901229-05 
1526 Printer ROM part number 325341-08 

(Our sincere thanks to Mr. A. Ryan of Ontario who provided this information). 



- s- c. — ' i z,~"B s z s c --. a i- zzzz'ZZ: ?si 

16 :UU_i. 



"Ucl ZO 



5 XT ASM BYTE C6^? T JL AT SODF^ 
r; y.T izSzl Bird Cd^rd 7 ^dd SlDFf 
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to 



Ire thro ::; r. t PROEAL ohould automatically send a LF nicer 
-~ r-r; : " setting of the following variables 

EXT BYTE APLPALF AT $0Df3 ; " : - ~*->3end LF after CI 

If your printer double spaces when it should single zzzzz 2 zzz zhzz "ariable to 
lc This can be done from the EXECUTIVE or a JoE rile --i z'r n SIT 3?o 
command c If it prints one line on top of the ztzez : sez ±z to SSC & "^hen 
outputting graphics or speciual escape sequences , you may need to turn this off 

(so a $C3 graphic lata byte -cn"t he interpreted as a CI and cause a s^zzzz us 

$GA linefeed oaza byte to be sent to the printer). 

^Iscj nf yoni rer^purer is a 11c or is connected by a serial rncerfacs- yen 
^ili neon zz set another -nrinble t: Z z~ psrf -rm graphics :r ssc^pe 
saqr-rces= This i£ not e TROllAh -ariebie, but a global Apple variable Lira: 
controls cne ROh output ronrines m the noole? 

£11 B7TI rlJSSCCZ AT SCt33~$CG-ri : Serial command enable flag. Apple 

PRESCCE = ; Disable Apple ROM processing of serial printer output 

This will keep the Apple from processing escape sequences to the serial port 
internally, and will pass them straight through to the printer o 

PROMAL automatically configures an appropriate printer driver for year 
computer during boot-up. in very rare cases, if yon are vising 2 printer card 
which does net follow the Apple standard : yon :ns y nn^e t :• snorly <~-:-rr o r -n 

printer driver* in this case : See ( s $ which tells the location of a 

pointer to a table of addresses for the printer driver input and output 
vectors. The table pointed to consists of a WORD holding the address of ohe 
initialization entry point, followed by a WORD holding the addres of the output 
entry point (will be called with character in A) . 
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PR0M5 ~ -iivide „ ~ u_ - ^z ~ z Z :rir j ?>" ~ iO 

asynchronous data ":-^^5::. r v _ - ~v; * - - Iir «. £1.: _ -17- : r - nil ' T_VE 

commands can be r.: ^ c r". t~ -h^ m ^-r_ in z ^ • : ; . :s ' tu:- r zz. : v; 

- -r device. Uqz « ir^-.-. anrly-. - -73L1-.1 ;- zzzz:z l *r:f vj_. r^rc _ rnc u^rm: 

to the T device. Ih~ ~ r— h- i * r< ~«"±^aly -7 h:rr-'l? - rrgrJ- " ; - - 

your telecommunicr -1.. r?=c - 7'i z " :z^z - zzr^-z y~u "zzi~^ -~ ' — 5 ~ ~ r ~- rhi~ r 
knowledge :f rhe z uiuiarurtc; 3 :f ~ats :. :rr;rr i..uri..rs : v::~b z- - : ' zzzz~ 
parity, etc. If 70 :; icn't yc : nay ~"i-h zz zczs^Zz a refarsr.ee bock* such a-i 
RS-232 Made Easy by l-isrciu h Seyei = 7c u nay also ne^r tc :.crs^ll be a f crrxan- 
ta^icu for your particular z>z6am, czz 3£-232 adapter* 

You can specify the baud rate, parity, number of data bits , and number of 
stop bits desired for the T device before opening itc This can be done either 
using the TMODE utility program, or by setting values into memory directly from 
a program. 



mQIS UTILITY 

The TMODE utility is a PROMAL program provided 011 disk, which has the 
following command syntax s 

TMODE [Baud [Parity [Databits [Stophits ]]]] 

if no arguments are given 9 it displays the current values, land is the desired 
baud rgts ; Ccefault is 300 \hren PRGMAI is .started} o Legal values car be 1 1 r 
300, 600/ 1200, 2400, 4800 s or 9600 Yea may also abbreviate 300 as 3 f S600~as 
bo 3 ate*, wTnen PRQMaL is bcotec up. che initial baud Late is set zz 300- The 
second optional argument is Parity. -hhich should be specifier 3 S On N : M. or 
h fcr sven 3 odd & none, 3a rk ci spacer respectively* The initial default ic 

r.a c The thirc arguaenr is B&tsMxe x/r.ich should be T zz 8.. The initial 
default is 8« The final cptionsi argument is Stepbits* *fcieh should be 1 or 
2. The Initial default is h Most syscsns uss 1 stop bit except at 11C baud* 
Optional arguments which are not specified remain unchanged c 

The values specified by the TMODE command will take effect the next time the 
T device is opened (or used in an EXECUTIVE command). The values set by TMODE 
may also be sat directly from a program, discussed below. 



PROGRAMMING TIE T DEVICE 

For many applications, programming the T device is very simple* Yen just, 
need to open it and then input or output tc it the same way you would a file. 
For example; 
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MOID MODEM ; file handle for T device 
BYTE BUIlll, _ ^1 ~' ; Input bufi : i T device 




me pririary ?i:.s^, rrr^.xiry : .: i~a*Lirg : T l r. a £ msn is riTrirlirg 
aituatii7; -her-- 7*0 data i^ iseti^sc 7733 i: is ai-pacr&l 
scstus routine is provided; to tell J07 -*7her. daie is ready tc read, 
additiciiu global 7-ariabies ais prcvidsd n ells- ^elsctir-g ^ if reran! 

in rhe file FE1SY8.S and are summarized be^ows 



EXT ASM FUNC BYTE GETTST S0FC6 | IRUE if reaay. ^irg-C input ? 1 -output 

EXT BYTE TBAUD AT $0DE9 r S-ill, ^200.7 =£CC 2 o-l20G s ^2i2C : C^rl^S^tl! 

EXT BYTE TPARITY AT $ODE* ; >ro~a : t-cr^d. 3=-rark 5 i-space" 

EXT BYTE TDATAB AT $0DEB ; 3=S I173, 1-7, £=i,. 3-1 

EXT BYTE TSTOPB AT $0DEC ; 0-1 step bit6 3 >2~3€op hies 

EXT BYTE TEOFCH AT $0DED ; EOF char - (CTRL -2 default) 5 unless TDEVRA.W set 

EXT BYTE TDEVALF AT $0DEE ; Auto line feed. $00=no 5 $S0«out 5 $4CNin, $C0=bo th 

EXT BYTE TDEVRAW AT $0DEF ; "Raw" mode flag. $60 « oc EOF or LF processing 

EXT BYTE IDE VST AT $0DFC 1 Status byte from last operation (see below) 

Function GEITBT requires or;e argunetit vhieh is either {cc test the ir.put 

status cf the T device) cr 1 (to test ttie output status) c The function returns 
HUE if the serial device is ready and FALSE otherwise* For inputs it will 
return TOE T±.en at least ^na character has bear received and car. be read. Fer 
&r„ example cf 0.0x7 to use GETTS11 see file TiMYTEPjxl S , 

The variables TBAUD , TPARITY, TDATAB, and TSTOPB can be used to set the same 
values which are set or displayed by TMODE , from within a program, for examples 

TBAUD=$08 
TPARITY=2 

This selects 1200 baud with even parity. The desired values should be set 
prior to opening the T device. See the SRECEIVE. S and SSEND.S files for 

examples of how to set these variables. 

TEC-FCE is used zo determine whan character should be treated as End-cf-Fiie 

for input from the T davice, defaulting to CTRL-Z ($1A) . The default value 
allows a remote serial device to be used for input to the EXECUTIVE by 
redirecting input zo the T device. TEOFCH is particulary significant for 

programs which use GETBLKF to read from the T device (generally not 
recommended) . 
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The -pple 11 ? defies driver sncp : :s the ^ppd e Sup-r car- and tine 

cmpatiola ceres- and "lie ople He serial port tc Ixr cczil:ui flexitili tv s 
che T?0:i-T ia^ice dri^s- 2c:n^;lstcc the 5531 c' - h^riuace directly e 
Therefore it dees not support the Apple Pascal escape-sequences for selecting 
c o-munic^ zLz :.. ufori^utes^ etc- — *hich are nns oira^e for :aaz.-y applications/* 
PP.OMAL does not support buffered I device inpuc using interrupts » because 
'f the iuccnpatihili ty :f scxe serial ?urhr ^ Thic rasoo that your application 
prcgrac nay have difficulty "keeping up** vi th ?a iucoiring stream of characters 
or rr the "1 device at higher baud rates if Ic does extensile screen output or 
c ;her tfua^uwusuning ae -It: ties « Lupe. t picgriuiuara vich serious nclanennrri- 
cstions applications nay "ash to write chair own interrupt service routine., 
following the guidelines in the Apple Reference Manual o 5cr this reason^ or 
iu order to support incompatible cards * PRGMAL leases "hooks" for writing your 
ov7n T device drivers c If your serial card doe? not have a 6551 chip ojith its 
date register at $CGa8c you wi^i have co -jrite your ovn driver to use the I 
devi-eo^ 

The #CRD at $CCF1 Apple only:; is a pointer to a cable of hGRDs containing 
One addressee or che iniriaiiza ticn 5 status, input r eno octpur roucir.es r 

respectively „ need by the PZCKAL 7 device, 1; I sra nuehlne language routines c 
The INIT routine has u: argusencs and returns nooning o The STAIoS rouorue 
expects A-0 for incur :r for : itput . retorns the status in A r and the carry 

hit set if ready . The If: PUT routine has no argonaut £ snd io turns the character 
in k* The OUTPUT rentooe expects the character in A and returns nooning « 

The TDEVST byte is set by any status, input 9 or output calls, as follows J 

Bit = rarity error Bit 4 = Transmit buffer empty 

Bit 1 = Framing error Bit 5 ^ CCD not state 

Bio 2 « Overrun error Bit 6 = BSE. not state 

Bit 3 = Receive buffer full Bit 7 = Interrupt flag 

we nave successfully used the T device on the Apple at the full $600 baud 
uith the built in drivers (for example, the SSEND and SRECEIVE pro-grans'; . 
Naturally, this depends on your program* For example, if you attempt to access 
disk or have another time-cons using activity while characters are received , you 
will lose characters, in this case you should either arrange to have 
transmission haloed temporarily (for exampie s using XON-XCFF protocol; f or use 
a machine language buffered interrupt service routine • 
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nisj, ana luj 



, z z z z z " z c Z t V Z r ~ f . K ^ 



driver rill r-t-rr — v-^--?---ilc lnV c c=,--' - — " r O : ^ 4 ~ : ^ i: r^ptp ~'z 

the Break detected ~ ' z= f:z iz "ne status. 

When using ? r ~ z ~z. \zz z~z:: c ,a~ to dire? ': zzz^ezzzzz ,:hr :vph an Rr-222 le^sl 
ohifter such at ;ca 3 z.~::^:r£ 1C21^" ; z zz -rill reed u i~ additional 
programming to control ne special ivca^ f _ r,c :io^& ? 7c r example ; to .,se the 
model 1660 300-bard no den. , pec ""ill reed tc access ":1s parallel port fnsar 
port) to go "off hock" sftar ~z^. z_ r zz. the Z ia~~±za lie limziil pr:. 
illustrates how rc do this 3 icr other models or features scch s? dialing, ycu 
will need to consult your modem manual. 

2™*- jsersrai ^*- T a r-sc ctiiisi'" ~"z~z do -^^^ a^ce^*-"" 1 tOC 1 cod ?*°* *k~a Ocro'cacre 
although "ce , e had cn^ceso with 1220 band proviiei zzsz a long f8 bnrs t*' is rot 
send tc the Commodore at the fail 120 characters per zzzzzzz, karrrnlL p.. this 
depends en the ability of porr prcgran to keep 

The TDEVST byte reflects the status after any input, output r or stages call 
to the T device, as follows : 

Bit G = Mot functional Bit * = lot functional 

Bit 1 ~ Framing error Bio 5 - Ivor functional 

Bit 2 = Receiver buffer overrun Bit 5 = Not functional 

Bit 3 = Receiver empty / Transmitter full Bit T ^ Break detected 



SSEND AID SBECEIVE PROGRAMS 

The files 3SZr2~S and SREGBlfE^S on the PROMal d: s sk are source prrgrans for 
transmitting files between co^paters with PROMAL , at speeds of up tc 5500 
baud on the Apple or 1200 Laud on the Commodore 64. The fries do no c have tc 
be text files | any kind of PRQKAL file can be sent. 

The programs provided form a complementary pair. SSEND transmits a speci- 
fied file using an error-correcting protocol, and SRECE1VE receives the file on 
another computer and installs it on disk. The programs can be used to transfer 
any size file at up to 960C baud between computers in close proximity without a 
modea s by using a simple 'null modes" cable between serial ports s as shown 
below * If used with a Commodore 64 9 we suggest yon limic transmission to 600 
baud • 

The diagram below illustrates how to wire a direct-ccnnect cable (null 
modem) , with pin connections for the Apple 11c 5 pin connector on port 2, or 
the Commodore 64 RS-232 adapter ficdei 1011A or similar level skifzer* 
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" : rz - - ore h: ? 1 s. \ - : : - ^ nxi - r e : p J. 1 i.u 

?:r 5c _> T r:r5 I*h_- >> * _ rn 2 is 



6 : : / - — - - 1 ::. 5 
3 ■ 4 

7 .-■ " ' 3 
2 . 2 
20 hlh 'I" — — - -~: *;; : 1 



Two remote computers z&tl s.lsz exchange files a-- lis larf za'z- 

supported by the modem rsed typically 3 CO or 12C0 band), Uhsn using a richer 
instead of a direct connection ~ soma modif ieaticrs z-ay iee£ tc be -rale "c the 
program to send modem ccnr :.ol ocm^X/la: (srch as :z ~n3z 7 er ihe ::r-i:*' c These 

modifications are entirely dependent on the type of moo em -oeing aseuo -^glsu^l 

your modem manual for farther information* 

To traj-si:' a file- sr^rr ranelviag computer's program f~r 

example : 

SRECEIVE MYFILE.T 1200 

will receive a file eailee MYFILE.T at 1200 baud . Then start the transmitting 
computer's program (at the same band rste s of course); 

SSE1D MYFILE.T 1200 

The file will be transmitted in IK blocks with a verification "handshake" after 
each block is correctly received. If a block is garbled in transmission, the 
receiving program requests a retransmission cr that block. The program exits 
when the entire file 5s received. 

The source code for SSEND and SRECEIVE has comments which explain the 
operation of rhis simple communications protocol in detail. You may freely 
incorporate any part cf these programs in your own projects. 

TIHYTERM 

The TINYTERM program provided in source form on the P10MAL disk is a 
tiny terminal emulator program which provides the basic functions necessary to 
access a remote computer using an external modem. This program provides a 
"bare bones" communication program which can be used to communicate with many 
remote time sharing services, such as Compuserve* It is not intended to 
provide the functionality of commercially available communication packages, but 
is a simple program to illustrate the use of T device. Advanced users may 
enjoy enhancing it to a full communications package, perhaps adding the 
ability to upload and download disk files, etc. You may need to modify the 
program somewhat for use with your modem. We recommend 300 band operation. 
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I1W1C1 NOTES 




zzz 'zzz izza . z \ ^ : . . 71-.^": r -v Etirl --"Lsi- ^^a^Ci ^d^rlc : : 

ssrt tc the ncden tr cs?£ it :srrcrr. its srsrial ::;r::i:n5 as di-.lir.g 

r-lrg 55 ^f£ t~r<: c ^ """ovsc 7=^-5 rhere ere a nadeeriag vaztezy zz software 
"protocols'' ±~ nse T -~hich go~err„ ids as,^ informatior should be transferred 
":et"-""3S.: ds"":lre~ a:ts.chs-i >~ith r serial irisrf aca . 



itll thess factors nake it impossible to msks a ""one size fir-- 3 ?J1" driver 
fcr trie I de~ v i:.de Iz izi.zl^z~:i::zz.g the T ce"i:= T -a ha"s triad to xafca ?es™ 

to use for the vast majority of cases, and not impossible for the rest Zz is 
entirely the responsibility of the programmer to insure proper data 
communications fcr any particular piece of communications equipment. this 
should be considered part of the application program. 
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commodore 64 



2.7 t~ 

Application EXECUTIVE 
running running 
r-> 



Auxilliary RAM 
under ROMs 



PfPF 



FEOO 



Tar - a 2/ 



^ ? * " • ' y • 



= 3D OCG 



CSORG - 
=A2Q0 
(approx) 



1: c r:-r:s p / 



1 L Buffer 4 



area 




5 Moveable L 

6 Workspace : 



Space 



-ogress f 



H IF REE 



LOFREE 



LOMEK - 
=$4F0C 
approx) 



System RAM g 

$0000 — > — — — — — 



<— HIMEM 
— WLIM 

WORG 



PRCKAL 
Ran tins 



™ . : D000 



-5£ : ; r i --JFFF of the 

£-«ap £155. is ussi fc-r 
function >sy definitions 



*«ctSo An application prcgra— ca~ 
also use the space between CSORG 
and MEMLIM fc~ program :r --£r: 
space. 

A total of about 33K bytes is 
available for user programs, 
exclusive of all buffers, 
runtime package and library 
requirements, etc. If IJOREALS 
is executed (discard REALs) , 
about 2. 5K of additional space 
is available (moves LOMEM dovrr. , 

See the LOADer section for 
further information. 



Ail memory partitions shown here 
are on exact page boundaries . 



Copyright (G) 1986 SMA lie 



Rev. C 



COMMODORE 64 



0002 — 
0016 - 


Ml; 


>-=^-r-: b 7 inly) 
Mh ,-3;! r:r iLl^- 5 "..-.^cements 


> — / 
002B ~ 

cm? - 


~- ^ / ' * 


., _ " ^, , , 


(Czl - 
CC3^ - 
COFB - 

OOFF 


JOB ? 
ZZ72 
OOFE 


^ -5 6: 3" ** D -'- --\-C. _L<8 1 

mailable 

used by C-64 Kernai 


0100 - 
0200 - 
0334 - 


01FF 
0333 
03FF 


Hardware Stack 
Used by C-64 Kernai 

Available for M/L programs ;see note 2) 


'0 - 

nio - 


C7E7 
07FF 


Screen memory 
Sprite data pointers 


0800 - 
0900 - 
OAOO - 


08FF 
09FF 
OAFF 


Floating point stack 

Heap for Local Variables 

Scratchpad for I/O. encode/ decode, etc . 


0B00 - 


ODFF 


PROMAL System Data Area, see PROSYS. S for details. Reserved. 


OEOO - 
4400 - 
4F00 - 


43FF 
4EFF 
A1FF 


PROMAL Vectors, Jump Table, Nucleus 5 Library, & DYNODISK drivers 
PROMAL REAL processing routines 9 er Allocatable user memory. 
(Appro:.:* ; Allocatable memory for user programs & workspace. 


A200 - 


CFfF 


(Appraxc ) EDITor/EXECUTIVE space- ox user programs & variables. 


DOOO - 
FEOO - 


FDFF 
FFFF 


(Approxe ; EDITor/EXECUTIVE swap area and L device (RAM) 
Function key def s and CTRL-B buffer (RAM) 


DOOO - 


FFFF 


C-64 Kernai ROMs, VIC, SID, and 10. 


Notes : 

lo All addresses subject to change without notice c 

2. $0334 - $036F reserved for PROMAL hi-res graphics package. 

3. File PROSYS. S contains definitions of many system locations . 



4. See the Chapter 8 of the PROMAL LANGUAGE MANUAL and Appendix K for further 
information on memory allocation* 
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APPLE 11 




1EMLIM 
=$8E00 



-enables - r 



code 



: EDIT J 



OSORG 

=$6100 



<— hlFREE 



race 



Auxiliary 64K 



c Programs S 
& 

J OWN v&: s 
LOMEM « > 4 
-$2900 
f Azprox) 



/REE 



$0000 — > 



; PROMAL 
* Runtime 



Approximately 25B. bytes 

available for user 
programs, exclusive of 
all buffers, runtime 
package, library routines 
etc. About 2. 5K additional 
can be freed up by 
executing N0RZA1S (discards 
REAL arithmetic" r sad up 
to 2K additional can be 
freed up by selecting 
fawer than 3 PR0D0S disk 
buffers (BUFFERS command). 



WLIM - 
=$5B00 



PR0D0S 



s EXECUTIVE | 

1 I 



swap 



^cricst^Ece 
buffer 



W0RG — -> 
=$1200 

slice — > i 



CTRL -3 Cue 



$1010 > - 

$o&:c - 



;?-lcey def s « f 



Device 



<— $BE00 
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0200 - 257F AppI^ fi^rt :.f::rr_ used for scratch 

0280 - :i3F i,pplF Irfrer; Scratch path name buffer for P10MAL 

02C0 - 02FF -„ . b used for scratch 

0300 - :2ef ;^Eiii:i=: : : r - £icre 2) 



0400 - C.-FF 



Text aa_. i^^res;; 



graphics display buffer 



0800 




08FF 


Floatfrg ~ 5:a> 




0900 




09FF 


Heec fcr i:csi "cr: c .£-;l".s 




0A00 




OAFF 






0B00 




ODFF 


PROlifxL apster; data ^rsa (see PRCSrScS :iial c 


Reserved. 






j. UFJb 


-pro::. PZCKiLL Juc^ babies, table© 


j etc* 


1 loO 




13FI 


^scpros) PEGMAL REAL processing . cr Buffers 


/ allocatable space 






~ * .. 






1D00 




235? 


{ c an ws \:r r ) bi sk rr f f c r 5 - 3 f : r ?r dDOS 




2 coo 




8BFF 


;ran vary) Allocatable memory :cr aser programs & variables 


£ " ^ 




FF 


System spac^ - "' r EXECUTIVE & EDIT. Programs 


may over^-r" ~c 


8E0C 




S5FF 


PROMAL nucleus and library routines . 




BF00 




B?FF 


ProDOS page 




COOC 




FFFF 


Appls I, C e sp= .:~m memory * 




Auxiliary (bank-switched) memory; 




0?00 




05 FF 


Reserves fcr L device (library text). 




LOCO 




10FF 


Reservec for function key strings. 




* - ~a 

— ~= s~ v* 




::ff 


Reserved for CTEL-B buffer. 




1IC0 




j2FF 


Workspace buffer * 




^ V* \J 




3BFF 


Swap area fcr EDIT and EXECUTIVE . 





be ;s? = 

lc All addresses subject to change without notice* 

2c $3334 - $036^ reserved for PROHAL hi -res graphics package. 

3c File PROSYSoS contains many definitions of system locations. 

IbCREAL commarm causes allocatable apace to start az 1500 normally. 
5. BUFFERS command can change allocatable space. 

6a Developer's version allows applications without auxiliary (bank switched) 
memory or 80 column card to run (see Developer's guide) , 
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OB K *™0 B IIB 


*> - . .• : : . . 






OBCO 






rf; xi V -peoeii% ,Lc^ £ ^ <;*-ocl fifing loading 


OCOO-OC03 


STDIN, I 


3TDOUT File harrl=3 (r.aci-ac in LIBRARY. S file) 


0C08 


IOERROR 




Error code rrciL fisl frnctions (LIBRAR7. 3 ; 


OCOB 


BFILTYP 




Systam^daparfdsnr fils type for OPEN. 


OCOC 


B10ERR 




Disk I/O errcr : C=r^ : I«f ull, 2=read err s 3=wrt err. 


OCOD 


DFEXT 




•"C'\ dofec.lt file extarsion for PROMAL files . 


OC12-OC15 


DATE 




Lay, Month, Year-1900, 1 byte each 


OC16-OC17 


LOMEM 




tZaiz of Allocatable Memory 


0C18-0C19 


LOFREE 




Next available address fcr program load, $XX00 


OC1A-OC1B 


HIFREE 




First address not allocatable for programs , $XX00 


OC1C-OC1D 


HIMEM 




End of normally allocatable memory + 1, $XX00 


OC1E 


LDERR 




Loader error return code , $00=success 


OC1F 


NLT 




Number cf loaded modules, including EDITor, EXEC. 


OC22-OC23 


RANDWD 




Seed for rand en number generator (non-zero) 


OC2B-OC2C 


OS ORG 




Starting address fcr ZDITor/EXECUTIVE, $XX00 


0C2D-0C2E 


MEMLIM 




End of usable irssorf (if EDITOR discarded, C-64) . 


0C51-0C52 


MLP 




Address of subroutine called by PROC JSR 


OC53-OC57 


REGA, REGX, etc - Registers for GO command or BRK 


0CF2 


NOFNCHK 




Flag, if TRUE defeat default file extension 


OCFF 


BLINKD 




Blink delay for cursor. >$7f =solid , 0=invisible. 


0D00-0D50 


CLINE 




Current Command line, complete ( LIBRARY = S) 


OD51 


NCARG 




Number cf arguments passed on command line (LIBRARY^ S) 


OD52-OD73 


CARG 




Array of pointers to arguments on comd. line ( LIBRARY c S) 


0D74-0DC4 


COMD 




Command line split into argument strings 


0DC5-0DCC 


WORG, WPTR, WE OF, vJLIM - Pointers for Workspace (see also ODDB ; 


ODCD-ODCE 


LORG, LPTfu IE OF, LLIM - Pointers fcr Library (under ROMs, C-64) 


KJUUD \JUU\*j 


WSIZE 




Current Workspace size 


ODDD-ODDE 


GVORG 




Address cf start cf all shared variables , $XX00 


ODES 


TBAUD 




T baud (2=110, £«300, ^-600,8=1200, $A=2400, $C=4800, $E-9600) 


ODEA 


TPARITY 




T device parity (0=none s 1-odd s 2=even, 3=mark, 4=space) 


ODEB 


TDATAB 




T device data bits (0»8 5 1-7 9 2-6, 3-5) 


ODEC 


TSTOPB 




T defies stop tics (0-2,1-2) 


ODED 


TEOFCH 




T device end-cf-f ile char for input (def ault=CTRL-Z) 


ODEE 


TDEVALF 




T linefeed 9 bit 7= s l=add on output ? bit 6=l=strip on input 


ODEF 


TDEVRAW 




T Raw mode flag, $80 = pass all chars through as is 


ODFO 


TDEVST 




T device status for last operation, system dependent 


ODF6 


DRTERR 




Copy of runtime error (See Developer^ s Guide) 


ODFD 


PBLKCNT 




# bytes actually written on last PUTBLKF 


ODFF 


ALPHALK 




Keyboard Alpha lock flag, $80 = upper case only 


1000 


BKEYDEL 




Key for delete with pullback 


1001 


' BKEYINS 




Key for begin insert mode 


1002 


BKEYJS 




Key for jump to first char of line 


1003 


BKEYJE 




Key for jump to last char of line 


1004 


BKEYCEL 




Key for clear to end of line 


1005 


BKEYALK 




Key for alpha lock toggle 
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- : Zz^ 


PZEFZl 




' " ~ 1 




t ~ ^ y z 


- i-cgc so - :i ^^-li^F :.s in memory, $ j „ rz rot 


'ZZC 






- ----- \ i <~ r - — * . ngical dr: T - • , :.ei~r ;.t=8) 


ODBl 






- C-r- device # for drive 1 (9 for 15*l s S for H3D) 


wEl 






- -^d = Tsr-^rsitly disable DY^Cdd* r. 


-jDE3 




C64D7NG 


- Flag 5 580 - I/YNO en : $00 = DYNODISE eff 






C 8^7 3 A 


- Sercndary _rdd:;ose for Printer OPEN -Tea i^creiidir: J 


C dr ' J * 




r C -:?L T 1 


- Pricier rpper * dourer case s~rl :ch flag (See Appendix 


... • <_/ 






- Defies rrrxber for printer (Sea Appendix 3) 


cyst err. £.5 


dresses far 




OC68- 


-OCA3 


PRE J IX 


- Current volume & p&chnama (ends with ~ / " ) 


GDEG 




A30RTCH 


- Program abort character { c: s f a a 1 1 = C TRL -C ^ S00=none) 


ODES 




RAMUNIT 


- /1AM tini t number, normally SBG-sIot 3 drive 2 


ODE 6 




GSLOT 


- 51oz for Is. 2; drive, normally 6 


ODF1-ODF2 


IDSVTBL 


- address of I de /ice driver table 'see Appendix ?) 


ODF3 




APLPALF 


- Auto line feed flag for printer ( $80=yes, $00=nc) 


0DF4- 


-ODF5 


APLPJT 


- Pointer to printer driver veotcr tabia (points 








to Init ptr word, Output rtr ::c rc A=char) 


ODFB- 


-ODFE 


DSKBUFS 


- Pointer to disk buffers . 



All addresses subject to change without _rc :ice. 
2. File PROSYS.S contains the definitions of rhese and ocher system 
locations » 
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The PROMAL COMPILER and z^ , :z 

space, and under some circumstances use the Js^ z-^z^ n^e zz^-, zz :z^ 

COMPILER "B" option on the Commodore 64) the zz;€zz r~z~z<~\z : -~ 
EDITOR for buffer su&ce. With care, user-wri.,"-^ ^zz^zz.z,^ xcj i: 

; ~ .. zz _~- . ry ^z^zz zz ne System Area ^r r j>enc: 3. - understar.1 , 

varii ir ^/errel : in discuss!* ich are define*- 11 fils 1 10S T - 

Additional, inf emotion Is contained in the section on the LOADer . 

When a user program begins execution it can safely use ail memory between 
LOFREE and HIFREE fc buffer space. This Is the area shown as "FREE SPACE" by 
the MAP command. 

Zz the Commodore £4, you may also safely use the Wori^tnc? for a turner 
i: is empty. The Workspace exists between WORG and WLIM-I • If WEOF = WG1G, 
tnen zhe Workspace is empty. In any event, the space bee-Jean iEOF and WLIM-1 
Is unused (this is the "FREE WORKSPACE" area shc-r, by the EA? command). 
Naturally chase pointers will change if you write che Workspace in your 
program. They may also move if you use the LOAEar to load a program or overlay 
which does not OWN its varieties (not recommended) c You can "force" the 
Workspace clear by setting WEOF and WPTR to W01G= 

On the Commodore 64, if you want to use the space occupied by the EDITOR 
fcr a buffer, you may do so. This Is the space between HIMEM and MEMLIM. if 
you specify "OWN" on the PROGRAM line of your program, ic:: example, 

PROGRAM MYPROG OWN 

then -z-.i :z~z z^a memory between WL1M and MEMLIM. This Is because specifying 
"OWN" cn the PROGRAM statement forces the PROMAL EXECUTIVE to allocate your 
global variables at the and of your program rather than at the high end of 
memory as It normally wonld if using the EDITor space, yen should set the 
EDRE3* flag Z.z z (defined In PROSY- cS) The EDITor will be reloaded from disk 
If needed iacer. 

Note i This applies only while in a user-program. This ares of memory Is 
absolutely vital to the EXECUTIVE when it Is running. 

By using the NOREAL command and using all the above techniques., it Is 
possible to free up more than 34K bytes of contiguous space for a user program 
and data on a Commodore 84. 

On the Apple II, about 28K can be made available for programs and variables 

by using a NOREAL command. 
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1 - -'jz: i= i'o-.i 7- r ~ >:7 1. is^^t./r l-r^ca^ -rirc-utines from a 

-1 \>J! r^rsn- If €}: ~ ; - -laniLia. - 'it,: x~ 7..*' language program- 

rir.j- 7: n€.7 7 ~e:: ski;; 'z\±s section. Beca : ;s3 ??77iC : f ~*~nctionally very 

_ . language, ir : z r::rmell7 -:t n^' -e.-^,^ -„-^ any machine 

7 an 7" 3 frrgrarriing at all with PROMf 7 i---e"sr- l" c 7\-r T ~ant to use machine 
language routines, a clean interface f e ' - -"lied. Ion can even pass arguments 
to £ machine language routine, jnet 1~ a ?r 3K*7 ru Droutine. 

The way you call machine language routines depends on wfcac you want tc co <• 
We might categorize the usual needs as follows, in order of increasing complex- 
ity: 

1. Call a ROM routine t:,ac is bail:: 1"- 7 our computer. 

2. Call a small routine you wish zo embea m DATA statements es part of 
your PROMAL program. 

3o Call a separate subroutine- package, possibly with many routines and 
passed arguments. 

These cases are well-supported vitc PROMAL . We will address each In rz6.es, . 

PROMAL has a very powerful way of calling machine language routines <> It is 
especially useful for calling ROM-resident routines, such as che C©m@iofe 
Kernal routines or Apple 11 Monitor. Virtually any 6502 machine language 

subroutine can be called directly from PROMAL with this method « This includes 
subroutines which expect arguments passed in registers, or return values to the 
caller in registers. This method can also be used to call machine language 
subroutines embedded in PROMAL DATA statements. The key to this extremely 
powerful and simple capability is the builc-in J3R procedure s described below. 



DECLARATION § 3X1 ASI ?S07 JS2. i£ S0F14 (defined in PROSYS.S) 

USAGES JSE L A<? cress ■ ; Arsg [ : Xreg [ 7::reg [ s Flags }}}]] 

Procedure JSR calls a machine language subroutine at a specified address, 
optionally loading the 6502 processor's hardware registers with specified 
values before the call. Address is the address of the desired routine* Areg, 
Xregj Yreg, and Flags are optional arguments which specify the desired values 
to be installed in the A s X 5 Y, and flags (processor status word) registers, 
respectively o Ail register arguments should be type BYTE. Naturally the 
address :=-jst be type WCRDo 

In. order to use the JSR procedure, you will want to include the following 
declarations in your PROMAL source program (or INCLUDE FROSYS, since PROSYS.S 
contains all these definitions) 2 
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entry point 
Subrt . addr < 

A 
X 
Y 

Flags 



lines ' z zjl- _ r 1" , *tion of the built -in procedure JSR, and the 

locations " - c : : : £" " processor regis?---: contents to be used. These 
7 "nl ": - explain: - • - ri - 

I-ie-e i& how J ZE -oris. ^;:s: jour PRO<^__ program executes a JSR statement, 

■;h- itc c^e ~ s srgrrzenr :„ = :s~:\ef into MLP, and any additional arguments are 

copied in~c 1EGa s 3LEGX. REGY, and REGF , in that order- The 6502 registers are 

then loaded as fallows : 



REGA into zl.e A register 
REGX into the X register 
REGY into the Y register 

REGF into the flags n.cessor status word) 



and a machine language jump to subroutine is performed to the address in MLP. 

When the called machine language program returns (:. 7 ith an RTS instruction" , 
the contents of time registers will be saved in REGA. REGX, REGY, and REG? 
before resuming execution of the next PROMAL statement. Your program can 
therefore examine the contents of the registers at the time of return. This is 
important since many machine language routines return values m the registers. 

Any optional arguments on your JS1 statement which are not specified are 
not changed. Therefore, for instance, if you JSR to one machine language 
routine and then JSR to a second routine with no registers specified, the 
registers will contain the values returned by the first routine. 

Some examples should illustrate the simplicity of this method. The 
examples below refer to Commodore 64 "Kernal" machine language routines , as 
defined in The Commodore 64 Programmer's Reference Manual. Ail the examples 

assume you have added the declaration lines given above. 

EXAMPLE 1: 

; Call SCREEN Kernal routine - returns X=columns , Y=rows . . . 

JSR $FFED ; Kernal "SCREEN" routine 

OUTPUT "#C SCREEN IS #W COLUMNS BY #W ROWS" , REGX, REGY 

This program fragment calls the machine language routine at SFFED without 
specifying any registers c It then prints the contents of the X and Y registers 
which were returned by the subroutine. 
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EMMPLE 2; 



BYTE LINE 
WORD i 
BEGIN 
JSR CEhlh 

1=0 



chanr- : ' 



JSr, CHRIN 



input char 



i::i:e[I]=rega 



install char 
next location 
end of line? 



1-1+1 

REGA=CR 

JSR CLRCHN 



replace CI with end of line 
release channel 



put i:l,line,nl 

END 

This program f ragmen, reels £. lira from the disk error channel and prints it on 
the screen. It wi^l ncvrmally display: 

00. OX, 00, 00 

The JSR CHKIN calls the Kernal CHKIN routine, passing in the A register and 
15 in the X register to select channel 15c The loop repeatedly calls CHUN, 
which returns the character read from the disk drive in register A. The value 
returned in register A. is then installed i" € string. When a CR is received 
from the drive, the channel is closed, the string terminator added s and the 
line displayed using an ordinary PUT call. Note that when using Commodore 
channels like this you should be careful not to mix nerval PROrlAi 1/0 calls at 
zhe same time your channel is open, because PR0MAL uses Commodore channels to 
o;o izs l/l* &ud only one channel can be selects J at & time. ALee, channel ? 
Is always open tc trie Command/Errc. channel c ne disk driver If you open 
your own channels ? you should use channels and secondary addresses of 8 or S to 
avoid conflicts witr. normal PR0MAL disk files. Be sure to close them, tool 

notes oi jsr mm& 

1. When you call JSR ? the address is also an optional argument - although it 
is usually specified «> if no arguments are specified, a call is made to 
whatever address is in MLP . In this way, you can call one out of a number of 
possible subroutines selected from a table, by putting the desired address in 
MLP before each JSR call, 

2* If a machine language routine executes a 3EK {breakpoint} instruction, 
the address of the breakpoint and registers are stored in these same locations 
before control is returned to the Executive* 

3. For the Commodore 64 2 Do not attempt tc call any routines in the BASIC 
ROM because PR0MAL switches the BASIC ROM out of the Commodore 64 memory map. 
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IF REGF AID $80 

j&UL'^KG A lUCWLZs La^QiAS iLGu^IIil Z~£ S^r^ s2MIME^£^ 

Many BASIC programs have machine language suDr^ctizss embedded in DATA 
statements. These instructions are READ and ?CKEd into some unused area zf 
memory and then execrtec -- 7 irh a jSR or SYS statement. i:cu can also embed a 
machine language rouci^s ;c: routines; in 2K0¥n%L TjaI^ sea tements , and execute 
the code using JSR. Zz is rcice a sit simpler than BASIC though, because you 
do not need to use a loop cc it and POKE it first* 

There are two ways to set r«p an embedded machine language routine, depend- 
ing on whether your routine is address-dependent or address-independent* An 
address independent routine is one which will execute correc llj regardless of 

the address at which it is loaded « An address-dependent routine will only 
execute properly at the address for which it was assembled. This distinction 
is important because, in general > your compiled PROMAL program (and therefore 
your data statements) T fill net be loaded into memory at the same location every 
time. 

If your routine is address-independent (runs anywhere) * then you can 
execute your machine language routine by simply using procedure JSR to call it 
by name. If your program is address-dependent, then you will have to insure 
that it is executed every time in a known location. The easiest way to dc this 
is to use procedure BLKMOV tc -i-coy it to a known location and then JSR to chis 
known location. This method is equivalent to the READ -an d -P KE loop method 
used in BASIC. 

A machine language routine will be address-dependent if it contains any 
references to addresses within the routine itself. For example s if your 
routine does JMPs or JSRs to labels that are part of the routine itself s it 
will not be address-independent . The same applies for a LDA of any data in the 
routine. Conditional branches are okay, though, because they are coded as 
displacements, not absolute addresses. 
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EXAMPLE : 



BYTE LINE [81] 
WORD I 

data by*: i :.:l:; : el : \ - 

$C , "A" , ; TOLOWER C¥2 v \-. ' 

$-:.-: ' ; ^r" 

$C9,$5B, ; i_ 

$?: 2 ; ™ ;r:r 

$69,-:l: ; ; a / ^ : . 

$60 ; SKIP RTS 

BEGIN 

POT "ENTER A LINE; " 

GETL LINE 

1=0 

PUT NL,"1J LCv. ERCASB ONLY = " 

WHILE LINEii; : not end cf spring? 

JSR TOLOVLru LINE L I ; ; convert char 

I=I-KL ; ^ump pointer tc next char 

PUT REG A - show returned result 

PUT NL 
END 

The program fragment above Illustrates a call to an address-independent machine 
language subroutine embedded In data statements • For simplicity, a trivial 
routine was selected, which simply converts a character passed In the A 
register to lower case If It Is upper case and returns It in A. The line, 

JSR TOLOWER, LINE[I] 

calls the embedded machine language routine, no matter where the program Is 
loaded, passing the character desired in the A register. Of course, the actual 
conversion tc lower case could be done much simpler with the PROMAL statements, 

IF LINE [I] >= 'A' AND LINE [I] <« 'Z' 
LINE L I j - LIKE [I; + 320 

but this Is ; as we said, siapl^ for Illustration. 

if your machine language routine Is address-dependent , you will need to 

copy It to some unused memory area and then execute it, for example J 



CON MYSUB = $0334 ; Where to put M/L sub 

DATA BYTE MYSUBCODE [] = 

. .. ; (put hex code for routine here) 

DATA BYTE SUBEND [J = ; dummy byte' to compute Ice of end of code 

BLKMOV MYSUBCODE, MYSUB ,SUBEND-MYSUBCODE ; Copy routine to known loc. 
JSR MYSUB 
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There are two ways your unchine language routine can be loaded into memory. 
The simpler but less power ; ~ n r - :o use function MLGET, described below, to 
load your program rt n -reel::- zl ess in memory. MLGET can load machine 

language programs generc .sc r; v virtually any assembler for your computer* The 
only tremble is, you ha^e ^ fii-d a place to put your program. Since PROMAL 
£l„^^-c& memory dynamic c l^y 1 ... \. programs, you will have rc choose carefully to 
a^oic assembling your program for a location which may be ; rrupied by some 
other program. There are a few "holes" in the memory ucec, 1 mussed below, 
where you can locate your machine language routine using tuis method. However, 
if your program is large, you should probably u . " -ice MLGET to load your 
program. 

The second method is extremely powerful. This is to create a relocatable 
machine language PROMAL module, which can be executed by simply typing its name 
from the EXECUTIVE, or can be loaded under program control with the LOAD 
procedure. PROMAL 2,0 provides a utility progrex on the iSZlikZ diskette .ailed 
RELOCATE, which has the ability to turn any assembl y program into a relo catable 
program* Your program does not have to be address-lndepene er t c It can be used 
with virtually any assembler. If you don't have an assembler, one is provided 
that runs under FROHAL or: V:lume 1 of the PROMaL Public: Eomair Jser Library 
* available Zl^il 511-/- 5- ^slag RELOCATE, you l>i h>-c a rachiue language 
decile ^kiec ~rill run properly ar any address voicr tire rRvti^r _cacar car rind 
available for ,: > This technique is described at the and of this section - 

SOS-SlL^^x^LJ S£^ZL51 It^SSmSi ^GUIlllS USHG MLS1T 

The biggest problem cf a standard machine language routine is where to put 
ire As you know, PROMAL programs are relocatable, and tne EXECUTIVE 
chromatically finds a spot for them in memory c Unf or ornately s 55C 2 machine 

language programs are not generally relocatable, end will only work properly at 
the address they uere assembled for. Although the FROMAL EXECUTIVE can load a 
no n-relcca table uachine language program into nexnory with the GET command, it 
won^t keep track of where it is f and may allocate a PROMAL program (or 
variables) right over the top of ir if cere is not taken. 

If your machine language routine is short, one best place to put it is at 
$0334 to 803fF^ This area is available on both the Apple 11 and Commodore 64, 
However, the optional PROMAL HIRES GRAPHICS PACKAGE uses this area for global 
variables, so you should avoid using this area if you will be using hi -res 
graphics in your application. If your routine'^ s) take more than 200 bytes, 
you'll have to find another spot <. If you are certain your program wen": need 

— — __™ 



progress - Then. GET 7:";r PEOi v IrJL program into descry « "Ihsn use c r.e command 
tc daLemiii vhe: a the "available space" starts. Round this address up to a 
nice round number to leave rocic f^r future growth of T/ cur program, and use thi 
for the address cf year machine language program segment. For example, if the 
free space goes frc^ ?5?C0 tc $7A00, you might want to pick $6002 es t:ie 
starting address of four k/L code* Appendix ^ *ives a PROk^ memory map. 

Once you "have decided where to assemble your program, the ne^; problem is 
where to put your "zero p?ge" variables . The only zero page loc^tfns you 

can use with complete safety are; 

Available zero page fcr ^ommodore 64 

$02 - $10 (not used by ?R0MAL, but used by BASIC) 
$FB - $FE (the same space that is free for BASIC) 

Available zero page for Apple II 

$00 - $0E, $4 A- $*D ; 5BG - $FF 

As you already know if you"ve done much 6502 machine language programming ; the 
Commodore 64 system software cses rp almost all of pegs Co Unfortunately thi 
situation is not greatly improved v:Ith PR0MAL • However r 11 rou just need some 

scratch space for pointers and the like, you can use the following locations i 

Scratch zero page locations f o r _ Cci araedGre 

?ic - $1$ i Used fcr scratch by PRGMAL 

$36 - $41 ; Used for serarch by the LIBRARY routines 

S57 - $66 ; Used only for REAL arithmetic - free if no REALs needed 

Once you have settled on where to put your program and zero-page variables 
the hard part is over. Calling your machine language routine from a PR0MAL 
program is very easy* All you have to do is declare the name of the routine 
and where its entry point is. fcr example; 

EXT ASM ?R0C MYR0UTINE AT $0334 
EXT ASM FUNG BYTE TEST1T AT $0337 
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f^it ZZ 



write 



Litine and just return when von are done via an ITS. More 
: ' 1 want to receive or ~ :r :r_re arguments from the calling 



PROMAL Pets ses 3.r 



^ : " € - z z - lack. Ail arguments are passed 
£s l-byre cusnrltias - a~zez. if zze a :: r rrerr evaluates as r~pe BIT! yins high 
order ::: ":: -ill la C ir thir z-ss', - rssairg 1Z-1 Ergucsris ;t rsserlli; 
language routines is r:c t raecssendad. On entry your rcutine r the T register 
*lii contain ere number of signaentp pssseo, on the stack- These ergumerts were 
rushsc! rr t he ^ ° rrl Defers the -J55,, sc they irs lor ic^H*" ,w utid ernes th 5 " the 
larrm address o Generally yea v:iil want to pop oft the rerurn address and save 

then pull ^ff the argmerrs (the last argument Till Is pcrred first*; and 
save tnon in variables of your GTn c when the routine is donee you should push 
the saved return address back on the stack and return. You don't have to 
preser ve any registers. 

rhe fullering example shows how to write an assembly-language procedure 
with one argument expected to Is passed from the P10MA1 calling programs 

; Sample assembly language procedure MYPROC Tith 1 argument... 

; in unused piece of memory*. » 

; save return addr . low... 

; & hi byte 

; save passed argument hi 
; & low byte 
Operate on ARG1 as desired here* then. • • 



MYPROC 



*=$0334 
PLA 

STA RA 

PLA 

STA RAH-1 

PLA 

STA ARGl+i 
PLA 

STA ARG1 



RA 
ARG1 



LDA RA+1 
PHA 

LDA RA 

PHA 

RTS 

• END 



I put return addr back on stack 



; return to caller 

; save for return address 



Here is the companion PROMAL declaration and a sample calls 
EXT ASM PROC MYPROC AT $0334 

mm® 

MYPROC X+l ; pass X+l to m/1 routine 
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1 i _ - d. 1 ~~r c d"' e r^r^e-v d^cl "~. r c:"j-nivi> ..^ ^- • . •.__/_ • ' -• 7 - : t - ---- s= " 

. .: . ^Tc.iledrle :?.:• tllldll ^.trl .1 , lit--^„ ' - ^.Ig _.d cd^ 11 

Maehi~- language 1:^.1 v^rd ids --^r*! ^ _f OMON which loads at $8000 

can la dire~ :!/ d::~:i. l^In-il : ! . ; Commodore 64, Others will have to be 

r;:: dtoii 3ASIC. tr.cs t — 1 5 " e e' : "sl our objec : rd;e on disk, you can load it 
into memory from, tie IdtXi-l J1....V1 with the GET command or by using tie 

MLGET function. When using GET f enclose the name of the file in quotes :; 
indicate tnzt it is c nEchine language f lis instead of c.. ?R0>iiAL. ptogra . Also 
be careful to type the name exactly as it is stored 1:, the directory (usually 
with upier LcLcs 1.3 : r :.s::3] . for example; 

GET "MYPROG" 

will load the machine language file "MYPROG" into memc 1 y £. : v ever address i. 
was saved. Note that the MAP command will n:t show the f > where til? 

prcgrsH: is leaded c alternatively , your application car, loed the machine 

language f ids itself t using the built-in function MLGET , described in belcv;* 
This is the preferred method* 

Let us noTv leek &t a slight Ij sere complex example. This example illus- 
trates a machine language dunce ion with one required argument of type WORD and 
one oocicnal argument of type BYTE : defaulting to ' " if not specified; 

; Assembly Language function MYFUNC (WORD f ,BY1- 
*=$0334 

MYFUNC PLA 

STA RA ; save .-l_rn address 
PLA 

STA RA--1 

LDA #" " ; default enly 1 arg specified 

CPY #2 

BNE MYFUNC 2 ; branch if only 1 arg specified 

PLA ; else discard dummy hi byte 

PLA ; get byte ^rgumerd; specified 

MYFUNC 2 STA ARG 2 ; save default or specified 2nd arg 
PLA 

STA ARG 1+1 ; save hi byte of arg 1 
PLA 

STA ARG1 ; save low bjze of arg 1 

; operate on arguments as desired here. . .then. . . 

PHA ; push result tc he returned to caller 

LDA RA+1 

PHA ; push return address 

LDA RA 

PHA 

ITS ; return to caller 
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WORD WHERE 
BYTE CHAR 



CHAR 

if my: c v. 



M MACHINE 



-JAGE PROGRAMS 



lou may call LlZ-inRl routines f rem your machine-language subroutines (but 
you may ret rail subroutines wrl^^ in PR0M4L) . The address cf the desired 
routine car, Irs sbusin^d frevz the listing the LIBRA?.-* 3 file Appendix C 
this manual. Pass your argumer — the 5 rack, remembering uhct passed 
arguments are always 2 bytes each. Do^t forget to set the IT register to the 
nuahe: c-f arguments you are passing* The f~ ~ .owing example shows how to 
print a message on the screen from an assembly language routine by calling a 
librarr ::j.tine: 



PUT - $CFlf ; Address PUT routine (from Library) 

; Print sn errcr message and then the character new in the X reg, then CR. 



IDA "KZRRMSG 

?HA 

LDA -^ViRRMSG 

f HA 

IZA 

PHA 

LDA #0 

PHA 

LDA #$0D 

PHA 

LDA #0 
PHA 

LDY f3 
JSR Pur 



ERRMSG 



DB 



; Push the address of the string to print (low) 
; then hi byte 

; push the character to print after the msg. 



: rrsh dummy hi byte (must U Z f ,. 
; ASCII CR : d argument 



; another ? fcr the hi byte 
; we're passing 3 arguments 
; display all three arguments 



diar.) 



'illegal characters %0 ;0-byte terminates the string 



From inspection cf the prcgraa fragment above s yen nay have surmised how 
the PROMAL LIBRARY routine PUT tails the difference between a single character 
argument and a string argument o If the argument is less than 258 (high byte is 
u; s then it is a single character c If the argumer-c is greater than 256, then 
it sust be the address of the string to print. 
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jLzIZZZ* Z. CL .--^1:1 Z^XMJMS WWCkTA^ZZ 

i t ■ '. . o_z._:„ • .... .. ^ ^ - . . . ..'11 ^z, 1, ~'f . . 

£rr?,r_tsgS5 cf "Oin? r.r,s^^ai zl si,^':2^ ;i:.L£ 1 7' GE r~ _.v>:l £ z oc £tt 

r„cr:-r sicca i^ble program are; 

lo lo~ program can be executs •. . .i: i;/ 'ypi-rg its rxie from the PROMAL 

£ ... c or It' j r 1 ike ? ny ^ ^ b e ^ ?r ~l-i 7 r : r t ? 1 

2. The PROMAL loaiti "il.' It - iree location ? .emory to run the program 
automatically . 

3. The program can be loaded under program control using the LOADer . 

1 can import variables and subroutines from your machine language 
pachage PROMAL programs which call it. 

His z.akes using RELOCATE the most desi rd^s rrathed of pi sparing large 
assembly language modules for use with PRiXAl 

To use RELOCATE , folic- 7 thase steps : 

1. Prepare your assert l v loo.iguage source program in the usual way, 
following ilia interfacing guidelines in the preceding sectiooc rf the 
organizational guidelines suggested in the following sect! 

2 a assemble your program twice, once with the origin ss: c seme arbitrary 
page boundary (greater than $0200) , and once wi 00 cla origl j. s-X exactly $0100 
bytes higher in memory. Save both resulting cbfaot program , Tor may use 
virtually sr.y assembler you wish. A public iooiai~: IP.OioAL assembler is 
available from SMA. The program should consist ct a single, contiguous block 
of cclfec Y: ur zero-page variables will not is 00.0 ~~ o.cble, and must be 
assigned locations as described in the foregoing section. 

3. Execute RELOCATE from the PROMAL EXECUTIVE by typing; 

RELOCATE Object OljactClCl Objmodule 

where Object and Ob jact 1110 are the names of the two machine language object 
files saved from the previous sosp 9 ard Ob jmoduli is tie name of the desired 
PROMAL module to be generated as output . No default extensions are assumed for 
the first two file names , which are normally "PEG" typs files for the Commodore 
and "BIN 88 type files for the Apple. The last filename will have a .C extension 
by def aulec 11 you want Objmodule to be an overlay instead of a program (see 
the section on the PROMAL loader for more information) , you can specify an 
optional fcuita argument as the single character 2 (ols letter "oh") . 
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.. .... ... . .• • . * , J, _,U>i . 1'- .• 1 •_ I i -~ ... _^w'^C,C — o .l — -., r -;-r ...r. -. t. ^«-vc<c: a 

yt i J -low some simple conventions, which we wl . :Il-r^.- iv 

example program. 

To organize your program, decide which routines yc • « -£~ : o call from 
your PROMAL program^ These should be entered by a junr table £t "he very start 
of your program • These JMPs should be followed immediately z:j arjy non-zero 
page variables which you wish to make available to the calling 2R0KAL program 
'"of" en ^ 7 ill be need~d) = For example, if you war*; °t3 to call three 

routines c,nd have one variable which can be accessed zy ether .7?.?MAL programs; 



TEMP 




fiOFE 


> 


Temp 0-page variable ~:s£c b~* "Li? prcgra^i 






CC-C 


> 


Dummy origin (make il $2 ICC fcr 2nd asssr-c 


FUNCA 


JMP 


FUNCA1 


I 


Function exported to PROMAL program 


PROCB 


JMP 


PROCB 1 




Procedures exported to PROMAL program 


PROCC 


JMP 


PROCC 1 






ANSPTR 


.WORD 


I 


Variable exported to PROMAL program 


FUNCA1 


PLA 










STA 


RA 


I 


Save return address 




• • • 




I 


etc. 




RTS 








PROCB 1 


PLA 










STA 


RA 








RTS 








PROCC i 


PLA 










STA 


RA 








RTS 










END 









Assume that this program has assembled successfully, low you want to export 
the definitions of your routines and your variable ANSPTR to the PROMAL 
program(s) which will be using your machine language package. Since the 
assembler can't generate an export file automatically 5 you can generate a 
"fake" export file by hand using the PROMAL EDITor o Assuming our sample 
package will be called MLPKG, you could generate this text file with the file 
name MLPKG . E : 
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P^OC^M BOOTPROG OWN 
INCLUDE LIBRARY 
1.1 .11 1 PROSYS 

LCA1 "MLPKG" , LDNOGO 

L _ ]ALLSML" 

Ei>I!3 

PROGRAM CALLSML ; sain module, calls MLPKG 
INCLUDE LIBRARY 

INCLUDE MLPKG. E ; Export file from M/L package 

• • • 

WORD MYVARflOC] 
WORD I 

ANS PTR=MY V AR ; Using rer labia imported fret*: f^cKG 
If FUNCA(23-rr7A3;i: % < IOC l Calling li : l fur.cli.ori 
PROCB MY^£|I^lL XYV^Rri-2; ? £ X'L prc-ad^ra 

• • • 

END 

These two programs can then be separately compiled. The fins! step is to nake 
our machine language package relocatable! 

RELOCATE OBJECT OBJECTIOO MLPKG * C 

assuming OBJECT is the output file from assembling the program at JlOOO % £r,c 

OBJECTIOO is the object file resulting from assembling it at SlICC. 

To execute the program, type: 
BOOTPROG 
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tight 1 ,ii ::-locaxe 



; - ;;'-v c ^ .; ^if- :r - — : r,z^ : ~ t *- 7-: 1 : •, -zcTT- ----hi : 710VJ::. s 

- ; - e : *: " ^c' - if I: : ha a* - . . : ; f '1 : : 7 . zh 111 . :^11 , 

^ '~ .~_ "". — ^r./-- ^ ;- c % p- z c. 3" * : ~ j" - '- ; - ■c.-- - OCCC J" 1 1 e ~ t 7 ~ 'CS30 f. l "C.'/I t Z 

1.111 1-hE "ill Is iCiuiE.c dciuxclcr- : c jac - ills- cz t^oa 151^ such £5 ire 

generated by the BriSIO SaTE eoxt&and* 711 s format oiasists of a ;:crd giving trie 
starting scdress, f edited ly a rusher"" inage or the object trcgrss, 

i-.pple 11 version assumes a standard ??X*DCS object file T ^ita a file type 
3IrI. 9 a oh ac is generated ~aita a BSrh~E cos^aad- The ^ocle -/era lea of 
RELOCATE is i&cre c duplex because tae inf crmatlcn abcar the starting location of 

the teEC-rv image is contained ir« che directory instead ' z tha file itself. See 
the PRODOS Reference Manual 1st ie tails. 

Ids fcraat :f the PROMAL relocatable o"o jact module which is generated as 
output from RELOCATE is as felloes; 

Position Field Name Description 

G FHEAD Header ID byte, set to $CE 

! FTYPE Module type, §11 for M/L prog, $05 fcr M/L overlay. 

2-5 FHCDBA Nominal code base address (ORG where assembled) 

d=5 - Not used, set to 0000, 

d~7 FHCDSZ Code size in bytes od .ae»cry image c Do not include 

this header or relrr^ti^ - ? count. 

1-1 - hoc "isecj sat to he 

£-11 FHDATE Data of assemble c 1 byts each fzz day, month, year 

(yeai-iSGO really), in that order c 

11 - Reserved. Set to $04. 

12-1D FHC0MD Program name followed by $00 terminator, as it 

would appear on a PROGRAM line of a PROMAL program. 
Not used, set to 9000. 



20-n The actual object coda memory image « The size of 

this field is given by FHCDSZ- above e 

n-fi-nt-2 Reloc. Table header, set to ""R" followed by "A" * 

--h3-~+* Count of number of bytes which follow* 

r45-and list of words of addresses relative to the start 

of the memory image above, where relocations must 
be made. For example, if the memory image was 
assembled to start at $1000 and starts with a 
JMP $112B instruction, then the first entry in 
the list would be $0002 (indicating the high byte 
of the address portion of the JMP instruction will 
need to be modified when the program is loaded) «. 
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The RELOCATE utility can accept a f :- _ * - i:^; --J t- * ~ = : - . - 

_ i: \ indicating - 1 the output obje~ : ~ ~il~ i- -n l£ v rn.. <.-=-* - 

v^_ 5 (the SIZE command will display - rv; ^ ' f '*./>" ^r c rf_~ ^ * » ^ f - 

-^abiJ^ly Overlay) • 

ZrZiI3JJF? S5P.YICE ROUTIHES 

Lue ^ linirnrions imposed by the architects::- ~ ' r a 6502 process*" i. 

not practical to write interru: ;. ^rrvice routine:: ir I13MAL. However -\ "y 

write and use machine language service routines* 

For the Cs^cd-orfes S4 S your program should prepare fcr using interrupts as 

f ollrrn = 

1. Turn off interrupts - 

2. Sa~-a the contents rf the interrupt ^~c: " r - location $C314-C315 
in another variable c 

3. Install the address cf "our service routine ir $0314-0315* 

4. Enable interrupts * 

5. Your service routine r:ll be entered f r- ^ : n; tial Kernal interrupt 

processing via the vector at $0314 c Tear service routine may not use 

any library routines, Kernal routines s or any other software. It must 
preserve all rue registers and the stack* If the interrupt is caused 
by the 1/ 60th second timer , you muse dc a jump indirect through the 
saved vector you extracted in step 2 c Otherwise, you must restore the 
registers already pushed by the Commodore Kernal and do an RTI • 



Because of the heavy usage of interrupts made by the Kernal, we recommend 
you avoid interrupts on the Commodore 64 unless absolutely essential. 

For the Apple ii, you may freely use interrupts in the normal manner. 
However, you may not call any Library routines in "he service routine, because 
they (and the underlying PRODOS system) are not re-entrant. You should observe 
all the restrictions detailed in rha Apple Reference manuals* 

Correct operation of PROMAL with interrupt routines is entirely the 
responsibility of the programmer. 
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iHDIX j 

'ORHARD REFERENCES 



•-^ - : _ : - iflfcii:i:: rf> ' ----- - - toward referenced, 

r£ c'l s^.rernal (but -:r:-v .-.^1_ : :- 



EXT FUNC BYTE E£? . All fct-e-f r-fars^c- " Irpression Parser 
EXT PROC STATEMI : J 7: : Ic - £ -~ .-sssir.g routine. 

You may then tur*s rsr-vard --:^e.:.c . ^=a routine, by calling 

the normal manner, for example; 

TYPE = EXP 

STATEMENT ASSIGN, SYTSTYPE 

At tfr,a desired lo-^i^ ~~ r :*:- -\~ normal declarative :f tta Procedure 

or Function., for example - 

FUNC BYTE EXP 

• • • 
END 

PROC STATEMENT 
A1G WORD ASGNLOC 
ARG BYTE RESULTTYPE 

• • • 

j+iottlcntL z:* rbase routines may fcllo" their deill-ive ^ ^ 

normal fashic:;, i z fesii =1, Mote that declaring a forward rsfsrerve ^ 'r.:is^ 
manner defeats tne cciipi ear's argument count checking and cT^- ^ eeaceleg for 
undefined subroutines, so be careful. 

NOTEs If you nave zee optional Developer" s disk^ ZIREF.S illustrates an 

excellent example cf tee use recursion for searching £ crse. 



'ORHARD REFERENCES 
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_ - 1 ZZZ I c 8 which contains the 

■ - - - c functions : 



ATAN 

COS 
EXP 
LOG 



LOG 10 
POWER 



SIN 

SQRT 

TAN 



- ^r^ie in radians) 
Trigonometric ecsire "aagie in radians) 
i^crs-tlal 's ";c the Z power 
L^atjral icgaritri.il rbssa 
Connon logarithm ,base - v r < 
rrrar ' Y~ ;r tee Y po-sr; 
irigonciretric sirs \ang^e radians) 
Square root 

Trigonometric tangent (ang. in radians) 




Y - TAM(Y) 



These functions £.11 expect arguments of type REAL and return results cr 
type REAL. They are provided in PROMAL source form instead of as built-in 
functions (as in BLSZZ] because; 

io Many programs do not need any of these functions, if your program 

doesn't need them, you do not have to have them in memory, which makes about 
L3 K bytes of additional memory available for things you do re-do 

2. if you do need these functions, you can simply put the statement 
INCLUDE REALFl™C Q 

in your program, sr~ trey will be included in your compiled program (assuming 
you have copied the REALFUNCS.S to your Working dichcrte used for 

compilation) s No other declarations are needed tc use the functions. 

3. if you only need one or two of the functions, you can use the Editor to 
extract just the functions you need and insert them into your program. This 
saves memory and decreases compilation time compared with including the entire 
REALFUNCSc 5 file. Note, however, that some of the functions call other 
functions internally. For example, SIM calls COS and LOG calls LOG2 5 so be 
sure to copy all needed routines. 

4. You can examine and study how the source code works. The algorithms 
used depend heavily on Hart, et al, Computer Approximations, published by John 
Wiley and Sons in 1968 and reprinted in 1978 with corrections. Comments in the 
source code identify which algorithm was selected. 
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- J ^"-M~-.l i ct_ * -" rid earlier had function ABS in REALFUNCS. S. 

— ^~ — li -rir ^andar 4 -.IBRARl ic:i :.r .proved convenience and 



Also induced sne of ::'ze PROMAL diskettes is £ file called FLOOR. S. This 

contains the ?EOMAL :^.c::.- FLOOR, which has the forms 

Realvar = LC Z * \Zj 

where I is d £Z^L vclue . FLOOR returns a z v.E^l tss-jI^ -^"•^h is equal t: ths 
lc rg^5 : rr^eger lass than or equal to the BZtZ ^rguner/: , For example: 

INCLUDE FLOOB 
REAL X 

X - FLOOR ( i 00000 .89? ; Returns 100000.0 

X - FLOOR (-3.8) ; Returns -4=0 
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IBM tZ ana ee^ioatiDles version *, hereafter rareii^ , ;o as ^hn rRv/>ia*, o ^ra 

information is oriented cowards trie a: ft" are :c"'l: r sr :;is:,ir 4 g to pcrc an 
existing 6502 program to the IBM, bu^ r» dsc . --~_L going from the IBM to 

the 6502. 



MAJOR DIFFERENCES BETWEEN §502 AND IBM VERSIONS OF PROMAL 

L There is nc EXECUTIVE in IBIl rROIIat 5302 PROMAL includes an EXECUTIVE 

program ^hich is a command snell slnllar co DOS on the IBM PC. There is no 
EXECUTIVE in the ISM version becsj.se rhe ICS shell provides these functions. 
Users of 5502 PROMAL should h^va Hide niif fealty adjusting to DOS, since 

the EXECUTIVE and DOS are fairly similar- 

2. IBM PROMAL does not supper i nrlrlpla programs in memory at onoe f since DOS 
does not support it. This generally presents no problem. 

3. IBM PROM/ f^ln names are Haired tc 5 characters plus a three character 
extension, because this Is Joe In5 acau.n IBM PROMAL supports full DOS path 
names . 

I3b taxr riles including PROMAL source files; aan^ lines terminated by CR, 

12 pairs, -hereas 6332 PROMAL uses only SH terminators s In keeping with the 
conventions of cr.e respective computers. This may canse some initial problems 
•^nen sorting source files from one machine to the ether c When moving source 
■files from 6502 systems to the IBM, you will need tc -*rlre a snail "filter" 
program to insert's linefeed ($0A) after each CR ($01). More significantly, If 
your 6502 program uses statements such as POT CR, . * c to generate an end-line, 
yon -nil need to adit year source file to change this re Fnn SL ^ Using 5L Is 
z referred since It Is oortable between either machine; in the 65C2 Library. In 
is defined as a single" character , CR. in the 13M Library, It Is defined as the 
soring Clnlrc When using a statement such as nUrPUT "tCc o n , yon do nor have 
to change' the #C since this Is defined as the appropriate neirline secnenee on 
either machine . 

5 c In of :2 PROMAL s the file handle returned by OPEN always points to the name 
of the file* This Is not true for IBM PROMAL , because standard DOS file 
handles are returned, which are small integers , not addresses. This is 
normally of no consequence. However, if your program depended on the file 
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FF-OXr-JL-c In aos: eases this should toe t-cee ? elgrrflccUt hardest s::ce the 
1B11 has a much larger :rh:r:rh space a^dlehle f:r rrrnlng ycrr program, so 
progress reccing orerlsys : u the lull --ill net need In th^ I~K 

versrouo It is pessule co ha~^e :ne PROMAL oregran: chain to another urogram 
using tre 30 S CaLL procedure. 

Naturally, any machine langu- g- nails j^i;-;-- usurer reels ":erc • etc* used 
:h:: you r prcg^e^e will not be por calls. 

p r ' Apple hat\ --re using the T de~rtue nay :e- tc la steered 1 : \ :sa 3n the IBM 
rC. The TMODE utility Is not suppcrref, the DCS uGLI eoimuard replaces this 
program. IBM PROMAL supports Interrupt driven serial I/O. 

I- jour program uses special leys Isueh as funnclon hey-; , you -/ill need 

to adjust the key codes as specified in Appemiix Be Function key spring 
substitution is still supported in ;.ne 311 -:-shui::r. ; :u j ru t f rcn* the DOS shell. 

12, If your program uses embedded centre 1 hays to salecc reverse ""idee mode, 
you ~i-i. nan a tc c range rnls sires the Ilh lees roe soppert a control sequence 
for reverse -Idee (unless ; T er use AFSI-SYS as described In ;;he DCS 
eccurer c&uio.;/ c - -unc-.cci-fe ore yr e v idee Ic*. saucrng .rcso ar^rrrures- 

.e "II f^r-trcr displays file nasss in a iiffereur force; :r che IBM PC, 
.soe-i^ ulch t_ce DOS SIE cerLnand ( / w eotior" « 

14. The line editing keys for use with GETL, EDLINE, and INLINE are somewhat 
different for the IBM version, consistent with normal key conventions for the 
IBM. 

15o CARG[C] is not defined in the IBM version o 

16 o OPEN for IBM PP.CMAL does not have a default file extension (io is ,C on 
the 6502 version* - 

17 e The RENAME function cannot have wildcards In the IBM version. Complete 
path names are supported, and you can rename Into a different directory. 

18. IBM PROMAL 2.1 reserves the following additional key words: LONG, STRUG f 
UNION, SIZEOF, SEARCHLIB . 
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7ca llGnlrl Sysraio Ztslzaz-s .;i^:n£ a. file celled REL_FILE.S which provides 
a set of PR011AL routines for using relative files from your program. A totally 
eomplers discussion cf relative files is beyond the scops :: r^r? manual, but 
here is a brief descrio oion c 

A relative file is organised into a number cf zz zee-length records c The 
size of all records in the file is the same, ana is established when one file 
is opened- The record size car. he from 1 to 25^ nnar?c ters . Records of 20 tc 

100 characters or so are typically jssdc For a database application^, each 
record might be subdivided incc fixed-length fields; for example, a customer 
name field, address field e etc- lr.es yen have opened the relarivs file on 
disk, yon initialize trie fileo Initializing the file allocates space on the 
disk for the number of records you specify and sets each record to "empty". 

Once you have opened and initialized the fiie 5 you may vrrite and read 
records by specifying the relative record number desired. Typically this 
record number corresponds tc a sequential customer number or some other "key" 
number by which the file is to he accessed. The first record on the file is 
number i (not 0) f the last record has a relative record number equal to the 
highest record number specif iec at initialization o 

The REL_F1LE. S file has the source for routines to open, initialize, read, 

write and delete relative files* Due to internal forms t differences , you may 

not read or write relative files as ordinary sequential files P or by using the 
Executive or Editor (exception: you may DELETE or RENAME relative fines). In 
particular, if you try to TYPE or COPY a relative file f rco: the Executive, you 
will get a "FILE NOT FOUND" error because the cype of the file is not 
sequential. Do not use DYNODISK with Relative files- 

To use the relative file routines, put the following statement in your 
program before the first reference to the routines J 

I&CLUDE RELJFILES 

The following subroutines are provided J 



Copyright (C) 1586 SMA Inc. 



Rev« C 




grsarer tlsn the ortral xaiciarr. • i^lar of <ia rar ters y~ >Ic~r cc rse rhe 

rt^-n. ' ~ - all--" f :r :ir i'ar-iaee Ze":rrr 131; temirstrr r 7 hirh rill '::e spperisf 
artcra-lcallr " : rs— rf istr 113 1^1 iri~£ rrlp ?i:,r~r ::..s relative 

£ii-e :c L/C- open at ^ --ine . ^ll^JrS^ nus" 38 eallae prior re an}" ~ther ralsci^e 

file routines. 

EXAMPLE : 

CON RECSIZE=81 : Up r? 61 lr: £ r^crrl 

DATA BYTE FILE= ?f INVENTORY. R" ; lii-nsre Is -p^ne.- 

REL OPEN FILE,RECSIZE s Iper relative file for 1/1: 



PROC REL 1S1T INITIALIZE RELATIVE FILE 



I:^-:cvc:c 11L 1111 1^1 li^«=& a P- e ; 1 g ^slp opened r alanine seord file and 
specifies the xaximar: zacsr ci reccns to bs siloes ted* Each record is 
initialized tc "empt}*" is r^ii string" - lliesrses (type WORD; is the desired 
maxinux iraaiber cf rs:crcs e If this number is large* the initialization could 
take several ainurss o It is only necessary Lo initialize a relative file when 
it is first created Rafter opening it; or nhen enlarging the maximum number of 
allowable records c lr is net necessary (cr desirable) to initialize it each 
time you open it. To enlarge the file f cr addi clone 1 records, yen can call 
REL^IMIT again with Numrecs specifying the ne T -J mx:i-jgc Records previously 
written will net be affected • 

EXAMPLE i 

CON RECSIZE=81 ; Up to 60 chars in a record 

CON NUMRECS=200 

DATA BYTE F ILE= " INVENTORY . R 9 ' 

RELJOPEN FlLEjlECSIZE ; open relative file 

1EL INIT NUMRECS ; initialize file with null records 
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¥ fiiJ.fi J. fi 



record size which was specified whe„- Lr_i . 




EXAMPLE : 

CON RECSIZ£=50 ; . ; :i : - t ars : . 

COP N T JM?_E OS 33 3 00 
£ :I r "z "JL:S~z ^ I 

WORD RECNUM 

DATA BYTE F ILE= "MYDATA . R" 

RELjDPEN FILE,RECSIZE 
• • • 

PUT NL," WRITE WHAT RECORD NUMBER ? 
GETL LINE 

INDEXES TRVAL( LINE » #RECNUM) 
PUT NL, "CONTENT OF RECORD ?" 
GETL LINE 

REL WRITE RECNj!-^ LINE 



The program fragment above p:nr:s £~r £--tr} 
text to be the desired reccii, Iz .l^a wril 



record number and a line 
..■a record specified. 



PROC REL READ 



READ RECORD FROM RELATIVE FILE 



USAGE: RELJREAD Recnum, fluff er 

Procedure REL__READ reads a specified record from an open ral&tlva record 

file and copies it ro a specified buffer, Ise^us :a tre desired record number 
x type WCRD > : between 1 and the value cf i^^irees specified when the file was 
initialized* #3u£fer is the address r-f u;ie desired buffer to hoi . d...3 record, 
which should be at lease as large as taa rsccrd size spacifiad when tha file 

was opened. The CR terminating the record ca disk is no •: returned in the 

buffer; it is replaced with a $00 byte so the buffs:: car. be treated as a 
standard PROMAL string. A record which has never been an will return a 



C&njright (C) I?SS SMJi Xme, 



lev, C 



null string without error. 



EXAMPLE : 

^Lr«5Q ; Up to -* _ > .t a record 
i,« S = JOO 
ne r 8 1 1 

" : - 7 -v ~ ~" T ~- r " : "DATA. R' 5 
• • • 

PUT NL, "READ WHAT RECORD NUMBER f " 
GETL LINE 

i NDEX= S TRVAL (LINE, #RECNUM) 
REL__READ RECNUM, LINE 
PUT LINE , NL 



The program fragment above prompt- f~r a record number and displays Lz zn the 
screen, followed by a carriage return. 



FR0C REL BSLS1S DELETE RELATIVE FILE 



USAGE; REL_pEL2TE Filename 

Procedure ZE1_LZLETE ie csed to delete am entire relative record file. The 

file should be closed whan REL_DELETE is called. All records will be discarded 

and the file space reclaimed for future use on the disk, filename is a string 
containing the name zf the file. The message 

{ 'C- S FILES SCRATCHED, -Jl, rv" 

will be displayed on the screen* This is net an error . 

EXAMPLE i 



EEL DELETE "MYDATA.R" 
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p mm mis close 



USAGE : HL CLOSE 

f i 1 a or wber Hnpp with. 

n the 1541 drd i :: d on 
ant to properly close the 
xi t from a program which 

EXAMPLE % 

m • • 

RELJDPEN "MYDATA" ,40 

REL CLOSE 



dat if -ou INCLUDE dd I.S_232 and REL_FILf»S : r c :r:^ra:r 3 you 

will get some duplicate identifier errors when you cciirid, : .eca^?e rod 
packages use and declare some .. I '/-..t aaiie Kernal entry 1c , _: >.ct this 

situation simply :~-r;~ T dichsrer d i.iese files is second in jvcr p^gram to 
another file, and edit it to ddce the duplicate declarations . 

The RELJFILE psdrsga requires version Id er larer of PlQldde 

1ELDEMO PROGRAM 

The PROMAL System disk contains a file called RELDEMC * S 3 This file is a 
simple demonstration program relative files using REL__FILle - sipporto It 
opens a relative fid called "TEST_REL. R" for up to 20 record^ ?f 40 characters 
each, and prompts you to read or write selected records - The zlz-z dsce you 
run RELDEMO , you should select "initialize" fron the menu bed re reading or 
writing records • A menu option is provided to delete the entire file ?£ you no 
longer want it on your disk* 

You car. study the RELDEMO. S program fc-i more information about using 
relative riles c Since the REL__F1LE.S support package is provided in PROMAL 

source ferm g ycu may also wish to study it to see how to use PROMAL to inter- 
face to the Commodore Xernal routines. Advanced users may even wish to use the 

same techniques to write their own direct-access disk routines « if you do 

decide to write your own disk-support routines in PROMAL, please note the 
following; 

lo The PROMAL nucleus slmfs lias channel 15 open to the disk crrsisirid/ error 

changed The routine REL_CHECK in RELJFILE a S provides a way to read rhe error 

channel * 

2, PROMAL allocates C-64 channels in ascending order, with the secondary 
address the same as the channel number. You should pick "high" channels and 
secondary addresses (9 or 10 recommended) to keep out of PROMAL" s way. 
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APPE 



sllETl ' - - - H " .: d ./ill 11 1~: - 



h'S.:„ -iiiiiliig -ir^ic^s "ith 



j; --.r- t'cc?, >• Li . ?3e0^._. is sac up cg -Si -^ii- ~i^- ^-j-.'e. if you 
• ia r-"^r; 11 iri^e .ar 5-5;-, jcu s^ccld -I'-S^cla £-rsr^I~: permanently 
ana set che dsvice naaibsi-s for sec,: ari-se = ~ 3. T'la _d do-e ;z» 



™dTE ' : 533 e & lei- iiiiss 11 ...il drive d :>r/ice 8, not 9 

POKE dii^lld cie-i defects Di!JC£^SIl permanently 

In sen £ f-riaatted disk in drive and types 



SAVE : "?RCMfiL" : 8 ; 1 

Then pm lis PROMAL diskette back in and type; 
RUN 

After the system is booted uc. -;>py ^ha ts 

You can use a commercial copier to d" : i 
command® 

TIME FUNCTION 

"V- us Commodore 64, you can read tie " 
which returns the clock reading in ^iffia 
s. HEAL lumber : 



;hi itlii ti Ti'ir new disk. 

: vri^. in the COPY 



clock -sing tits f in it * on, TIME B 
■ L ^±ziy ~ i dCth cf d £ecom. n 



EXT BYTE T"£I ^d $A0 
EXT BYTE TMED AT $A1 
EXT BYTE TLO AT $A2 
FUNC REAL TIME 
BEGIN 

RETURN TMdi ; d«G - TIC ^c5555-Vdl 

END 
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ITEM NOTES 



Some non-PROMAL programs . Apple produce ter . z : >- — 1 ::1 > - high- 

~? ^ch character set. These frJes may be converted t; _-:~ndard 
A ^"~ ""-'-es (as expected by the PROMAL editor and other PROMAL programs) bv 
" 9ir ? " :r " ™?- A ??™ 7 — ilfty program on the PROM-.L Zj-ai diskette/ The coinmand 

'^?^2ls i? :rs cf the file to he corrected a:ii ^te^fiLa is the 

^- c ^ ;i6;£e corrected file to be written, The CLEAR! IT 7 utility also 

:r - c ' :es ~-; 7 Ic-gsr zhezz 125 characters, so ths ; the resulting Newfile 

^ ^ccepjs^^s zc zha rxOMAL EDITOR. 

SPEGl£Z ?3C'MS FUNCTIONS 

T ' : - -~- ?r 0DOSCALLS=S - : zz^zza program fragment sui zzz 

calling Epsci-1 ProDOS funccicas : such as testing or setting file attributes) 

which c.a no, covered by bciit lc LIBRARY routines. The ProDOS Technical 
Reference Manual contains all the nsccess&ry details. 
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r .. s *:k~ zzztz j_ ^ you should ! - ~- ='.1 " ~k--I zLs' r: : > ■ i ~ 

i; :Lsf_:,2 :. ^ - ^: on: -f.ikup €~~77 _= 3S-i zzz ^~~-zzzzzz 

.7:3^::; isfc^i .17 702,:: 32£.L--i -k- - - - z-zz: ns>- 

^ ^77 zz ■ \ zzzz^zz^z _nd only worl ~ 7 :'7 k .: --7I~ ; -~ " c 7 c :/ : 

-7. : 7 f :11.3:-- Eue z^^iz ^'..-r 1 1.;' deleted, yc • . -r'v- zz^z -: ne" eery free zzz 

original disk. Note that or:.!" zae Deirc risr. is br^tsMs- leu nay sake backup 
copies for your own personal use subject z~ zz~ Likens sgrss-iierit o kaking 
copies other than as permitted by the license agzzamez,z is a violation cf 
Copyright Law and is a crime. 



For the Apple ii, you may back up your PROMAL diskettes using the ProDOS 
Utility Diskette which came with your Apple lie c: lie (available from your 
Apple dealer) • You should also use this program lo format new blank diskettes 
before using them with PROMAL* It is £ good tzez tc --"rite the volume name of 
every diskette on the label using a soft marks:. ^11 disks should have unique 
volume naseSo To make a "working disk" which can boot up PROMAL and do 
developments t,se the ProDOS ri_e -opier or z±.e PROMAL COPY or EXTCOPY commands 
to copy tne following files from the PROMAL disk to your newly-formatted 
diskette : 

P10D0S 

PROMAL. SYSTEM 
ED1T.C 
EXECUTIVE. C 

COMPILE. C ; Either Demo compiler cr full 

LIBRARY. S 

EXTDIR.C 

COMPEREKSC-d 

EXTCOPY ,3 . If desired 



All the zi las ato^e except the full compiler are on the Demo disk. 
COMPILE. C, EXTDIR.C s GOMPERRMSG . I and EXTCOPY. C are not necessary to boot 
up the system, but you will usually want to have them on the disk if you will 
be developing any programs. Once your system is booted up, you can develop 
programs with a disk which only has COMPILE. C and GOMPERRMSG. T (and perhaps 
EXTDIR.C) on it. tc leave more room for your source and object programs. 
Remember to issue a PREFIX * command when changing disks. You may wish to copy 
other files sack as PROSYS.S or REALFUNC S « S on an as-needed basis. 



If you have a /RAM disk, you may want to set up a BOOT SCRIPT J file to copy 
your working files to Os c EXTCOPY is convenient for doing this. 

It is a good practice to keep at least one formatted, blank diskette 
available at all times , with the Volume name clearly marked on the label. This 

will come in handy the first time you type in a big program with the Editor 
only to discover there^s no room left on your working disk to save itl To 
extricate yourself, save to W and exit to the EXECUTIVE. Then use PREFIX * to 
select your blank disk and COPY W Filename to save your file on disk. 
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tte using a single 154 
an MSD dual disk drive, 
a dii. ir.s ve. 

another diskette. 

" - . rz zz . :~ z.^ z 

^ tbau^E fist 

several of chase services such as copying, erasing, ;: ^naming and displaying 
ore directory nay also be done with built-ir. EXECUTIVE command? The DISKETTE 

utility cart copy 9 delate 5 and rename files of PIG type or SEQ type, with any 

legal Cormcdore nsze, 

Piobstly jour firot use of the DISKETTE utility will be to make a backup 
copy of the ?RCM*,L SYSIIk DISK or PROMAL DEVELOPER'S DISK. Be sure to read the 

License agreement before opening your sealed diskettefs;. It is important to 
uaks a eery of oil the luOMAL distribution diskettes and o rnrk — zz. z'ziz 
copy, so that in the event that any files are accidentally deleted t you can 
always get a new copy from the original disk. You may riake backup copies for 
your own personal use subject to the license agreement o Making copies c tr ar 
than as permitted by the license agreement is a violatxor of US uoryrigrLt lau 
and is a crime • 

It is very easy to duplicate the PROMAL SYSTEM DISK, although ra~asr zlzzs 
censuring because of the slow operation of the Commodore 1541 drive ; it takes 
about 15-1 j minutes to back up a PROMAL distribution disk. However,, "hie is 
time "ell spent . If you are fortunate err-ogh to have a dual drl -e 3ys"sr_ ±z 
^uly cakes 2 minutes. If yczz have a commercial fast-copier , yoc zzs % z use z"zsz- 
Zz is a good idea to put a ^rite-protect tab on your PROMAL diskette bsf-re 
proceeding. 

To run the DISKETTE utility, cut the PROMAL Demo Disk {or a copy) in the 
drive and type this command from the EXECUTIVE: 

> DISKETTE 

The screen will clear and a menu similar to this will be displayed? 




a ~ e z ( z i r a c t o r y } , 
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?re3s Y azz iYETjYY zz crzYirrta an en --1Y- or ;m z relic; .: , 

o..:ror,: . Y:*i rii: > 3 ^?>~d If -'c -~ ro_.cl :rr £Y T Y-:Y z- — rrase 

the sirr of too rcpy coffer ; tyro Y ond retorr:. You say use che kElli^n Lcey oy 
tzbslz fcr r **;"as' e reply z : r^s^i^rs needing a yes-or-no answer. You will be 
ore-noted vheo 1c s~"£p -risks If ycu have a si?a . s : rive. When your duplioar s 
disk"!.? rYoisYoY; lYo o^oj "i-o >~ radisplayil -ss Q and RETURN ro <?r± z - 

the EXECUTIVE- 

liolYYYo '-GIYYYZYY DISKETTE? 

for ^aur normal oper? riens , you will not need mos. :;f Yos filas supplied on 

the PROMAL disks, but will want the PROMAL system so that >c: car, "boot 
up" PROMAL from your working disk. The best way to do this- Is zz uss too 
DISKETTE utility to format z new disk and then copy only Ice roles you want . 

To format a disk using DISKETTE, select .the 1 option from the menu and' 
press RETURN. Again, just follow the directions. When prompted for a 2 
character IB, oicl any z xc z oraraoters Yoa: 7 c ■:■ £E no: used when formatting 
another di Ti 1- v^v rcocr zz s i~ f farsrt ID on each of your 

disks- This 00" "=Yo ' f-o r tslz drY:o: ICS trgur - s ore -zhen you ha ;~ o tanged 
discs - If yoo :^"e rue Yisoaclss -~izz. ore same ID but different contents 
anc s:-f r ": 100 : . tts arf ft loo nay be corrupted. 

After forma torrg your riskatts : iosert your copy of the PROMAL Demo 

disk in the drive and select the C option from the menu. Copy the follow- 
ing files ore at c tiro using trr C option; 

PROMAL 
EDIT.C 

EXECUTIVE, C 

COMPILE oC ; Or the "full" compiler froa the sealed disk 

LIBRARY. S 

COMPERRiMSG-T 

DATE » C 

wore tha: unlike the EXECUTIVE COPY coward, ro^ zzxzal ;^ta tos "Y.C extension 
si^Iielrly when copying files vrltn DISKETTE Alsc s sir.ee DISKETTE can copy 
files Tito any legal Commodore name (of typs PES or 3EQ}, you must Ye careful 

to type Im upper ease letters if cfee file yo-o wsst is is upper case (you may 
wish to use CTRL -A to lock uppercase alphabetic characters). 
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mSCEL-I^&£QUS OPERATIONS 

You can also delete and rename files i-rLth II5KETTE. When deleting, note 
czaz ~ 7 i Idcsrd? £,re accepts V e when you are prompted for a file name to delete. 
3a ""ery 2srsf il ~:hsn rsing -"ildcs - is - dcer^ la rr prompt for a char?.-, t: change 
your mine * When the deletion is completed ; the standard Commodore disk 
z.sssags rill indicate che camber cf ffles deleted •' "'scratched") . F~r examples 

01, FILES SCRATCHED, 02, 00 

rn-icates : lies were deleted (the number after "FILES SCRATCHED" 5 not 

refers , If rca message indicates CO files scratched, you probably spelled 

the r.asis -"rcrig 'dor^t forget you have to edi oC explicitly fcr PROMAL programs 
and match upper and lower case exactly) • 
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' ~On^_^ \ - r f\. z-nce for 

J— I It ' - ' "'.JlZ.i^ ~- - 5 n ?yn^tt: ""iagrams, 

h \ " I : if-t-.in^ ^ :n_n: :;.-:raiS, 



Consider the ::i::t - path tt tns nrkt fic-t-t:^ - " n is f syntax diagram 
which shows you hew to con& En ns;i £ ^nsn: 5-5 ciL^t, 

The symbols shown insica tyal£ t:?s k2tr;rr^£ :r runttuation which must be 
typed exactly as shown. The artir ftls she™ in re^§ngl2£ describe things which 
you . the programmer, must supply = Ine linss connecting the ovals a:.c rectan- 
gles show ail the legal oaths ~-"hi th yen n^y :a 1 i5o for example, to make an 
assignment statement, the first thing yon leea is £ TAR. This is the variable 
nane reieL^e tne resent of the assignment . Exiting from the rignf ~ ° 5 e of 
the ; "A< c rettsngl~ ; -je see that -te hana e "torn in thi rcac " r meaning :ce ran 
take nnj of the ths . If we gc "etrnight ?ne£a' £ on rhe middle fraenn n~ con. 3 
to an . ne! ni_fn en equals sign in it. Since this i- nn ns «?t-nld en i : e 

tea eqija^s sign- finally, we cant to a tsetnngnlsr hex called SfL? c This 
stands for 'expression" , which means ne nan :::t any kind of expression, theneo 

We already know about fonning expressions « frohanoly the simplest expression 
is just a literal number. Therefore 8 legal assignment statement could be : 



X=0 

which sets the vari-ll~ f ;:o C ^ We also kner that a variable can be used for 
an expression, so another legal assignment statement would be 2 

ZVAL=X 

We are assuming that X and ZVAL have been declared previously. We also know 
that more complicated expressions can he formed with operators . for example: 

CMlN-(ZVAL-i;/2 

But how de we find out EXACTLY what is a legal expression on the right side 
of an assignment statement? For example, is this legal? 

VB=X OR Y 

To find out, we consult the syntax diagram which defines an expression. Since 
yon already know that expressions can be quite complicated and involve many 
possibilities, you might expect that the syntax diagram for an expression is 
also complicated. In fact s it is the most complex element of the language. 
Let's look at the EXP syntax diagram, which appears deceptively simple. 
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Before finally conclr: ir.g th^ .„ e--~r *t€t&^es": i - legal, though, we must make 
sure that nothing else is ieo^Irc:£ ;;<:- fwll^y ,.h> t :.-e already have. To do this, 
we must trace a path fiot: the exit ef rr:? P.5LA11GF hex te che exit of the EXP 
box, a..l r.en from the ~xit _ z z,,c- 11 J 1::: -;h,. .ii£lGl STMT diagram to the 
end-of -1.' zz± symbol • Ths zz^i-zf-lzzz a;:-hr?l : : shcun -;s a down-pointing arrow 
in a circle, symbolical " r i ~v-.:i::.r £ r^rrirac sivrn. 



!%rrrrllj 'ecu won't z z zzlz tr.r- f"^§*j*f**;£ very time you write a 

.r-:i.c;L„.. i :.. ii 1_ ri wrrg £ 7 :• :■: z'ze compiler gives 

zz rir:r message, arc :i l£ ic: zz^z^zz "~z,zz ±z ~r ong , you can always 

r^z the zyz/-~x d±agz-'Zf :r rslr 11.: : vi:: T ~h^ :rs problem is. 



As an aside .z zze technically curiouc ^zz right be interested to know 
that the ?~^C>1AL ICillllEE is reallr; ;lzst a PZirhll program which tries to match 
your source program to the z} r rzzzzi Jiagramsi Each syntax diagram in this 
Appendix is implemented as one subroutine in the compile" Zz r ir stance ths 
COMPILER vrtrins procedures called EXP, SIMPLEXP, RELATION, TERM, and iLzzzR. 
Each of the forks in the road" in the syrzor diagram corresponds to an IF 
statemer z iz< :ie cf these routines. 1: "parse" your assignment statement ? tre 
ASSIGNSTM1 z : nine calls the EXP routine zhich calls the S1MPLEXP routine, 
stc=, in the zzz^z rzarnar as we jusr traced through the syntax diagram. If zha 
zczrpilar gets zz z. pcirrt z:here the next thing in your program doesn't match any 
zz the chcizs- _ i: zzzz^zz an error message. 

Not that > : oz hrc v how to read syntax diagrams, which era the "authority" on 
whxr is legal in zhl Ihrl , you can refer to these diagram -r hener sr you have a 
question about ths 9f legality" of a particular PROMAL statement 
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jArvIc.j—^y) — 



h-N CON DEF t 



EXT DECL N 



— COWN"^ GLOBAL DECL f— » 
— * j DATA DEF fr- 



— »fTNCLUDE>»r F!LE[^AMeT°»€TV^ 

»--<51DT"r— ■ f-KD— 



STMT 
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j— ^Creturn>- ^"^Ax'ij 




1 



! ^ 



WHILE STMT 



M. while )— H ~ex~p1-»CT) — i 
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VAR. 




PROMAL System disk 
Several demo 



a 



This program is discrssad briefly in the 2321 ?i0BL4L4 .narrxal. it makes 
-ztensi^s'use of sprites for snisstien cf £ billiards gs-Ee* also uses real 

:Iath extensively fcr ccxpnting the xotion cf t-e rails, and hes many conver- 
sions (type casts) between real and byte aaza ^ypes* 

BUDGET ♦ S 

This is a very simple demonstration program which illustrates how ic f c rn£t 
real numbers for output- It uses the file BUDGETDATA e D for data. The file 
BUDG£ID3^.T provides more information. 

CALCeS 

This program, when compiled, provides a demonstration program which simu- 
lates a four-function calculator with 26 memories (named A through Z) . This 
program is discussed in MEET PROMAL! . To start the program, just type CALC, 
and follow the directions o The Demo disk has the source code for CALC, which 
illustrates how to write a recursive-descent expression evaluator in PROMALe 
This orogram is only about 150 lines long (excluding cossseircs^ , yet it can 
parse" ar/. evaluate arbitrary arithmetic expressions ^ith nested parentheses. 

CHECKSUM* S 

This program computes the checksum cf a specified block cf nemcry It Is 
useful for determining if any bytes in a block of memory have changed The 
comments provide further information on operation and theory. 

CLEARBlT7cS (APPLE II ©1LY) 

This program uill be found on the System Disk rather than on the demo disk. 
It is used to convert text files generated by ether Apple 11 software which 
sets bit 7 of each byte to i 5 tc standard ASCII format for use with PROMAL. it 
also truncates lines longer than 125 columns 9 making files acceptable to the 
PROMAL EDITOR. it illustrates how to write a simple file filter in PROMAL. 
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DUMPFILE filename [Type] 




rressiing "lie ■:■ - T 1.11 s~j '"ill il.^nls^ the - - r r;; 256 r-'iss- Pressing £.n~" cthsr 
— 1 "~--i- " ir-imais lit :icgr£^. ILZllllI supports cucp re :: scire.: 7.: -1 

-e.: iunp £ file tc the printer- The source -and object code for D"M?r"IlZ >rs 
the Der_o dish :r s Spates disk- This program illustrates conditional 



.....^^^^ . _. - ^ ~ ^ ~ w „ r ^_„r - ~- ZC\~ .h/T C.-.e - w ' ss O, -ft. 

une CciEEodcrs to compile the orcgrair, e See the comments fcr aore ;L2:hrs> oior , 
FILE ... 

"ri5 pi eg ram cmpocso ire ''1 ; cl: : i.af rnl-srop rheclh of - file aril displays 
Ito This is useful for comparing fro files tc sss if chep are identical , The 
comae 0.0 s in the so.:: file enolair ore prsgrar, Lie:., rod inacrje lo 

contains good examples of hi ':. manipulation operators. 

FIND.S 

This program is discussed at length in the MEET PROMALi manual c lo 

searches a file for lines containing £ specified string and displays chese 
lines c 



ihi- 13 a denonpciacion c :: high-resolution graphics using PROMAL . The 

prcgrar, is self-sxplsna torj "dsn executed. The source cede includes procedures 
for defining and el earing one hi -res screen, and dravring points and lines. 
These routines can be extracted using the editor for jse with programs of your 
own design. NOTE : This program does not use or require the GRAPHICS TOOLBOX. 
The GRAPHICS TOOLBOX provides sscti higher performance and is much easier to 
use. 

INFILTRATOR, 5 "COMMODORE 64 ONLY) 

This is a fairly large and complex demonstration illustrating animation 
using screen scrolling, sprites, joystick input, and sound synthesis. You will 
need tc issue a WS C command to edit this file and compile it using the B 
option (full compiler) . This program is an excellent example of how to make 
good use of PROMAL procedures and functions to simplify a complex program. 

RELLEldO . S (JGEMDDORE §4 ONLY) 

This program is a simple demonstration of relative files, it is explained 
in Appendix M. 
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SORTSTRING.S 



-d br.'.^:- "-1ET PROHALS. ^ :: - 'ides a demon- 

-t, file access, printer access, and general ' ^h- 



^-z-am provides a general shell sort !- : srr^rg arbitrary 

-^V-'^v3, and illustrates how to generate =- - ~" £7 *--v--gs read from a 
':1s- ?ee rue comments in the source r:,^e for • 

- ^ .. . - ^ : ^ r3: : - - red to split a text f: "nich is 

- /~£~^:"-~ J±~ c-eliev fi-es, ^ file ^ be split sftsr a 

~ - _ _ ~ ^ , , - - - containing a specified string. The 

command sy:v- cy. 

SPLIT Scurcsfile ~: : rsef ile Seccrxl. 1c .cunt 

or 

SPLIT Se-rrsfiie Firstfile : fc-cr.cf i^s erring 

where Sour— fTil- i = t-s -iis Te ^li^ lirstfils i* -ha us^e 3 ? ize file to 
receive tr^-irsc cere sf S*s file, en/ Hecondfiie is cte ceiae :f cne file to 
receive tl- -h £ flla- Vc lef^clt fiis a^sio- are ? rovraed, 

on be sure -'nclude % 3' for r„crri£l source files. Count is ne number of 
lines t- —led fr--~ fs^rseiilfe u; JlrsSfils: tzz rest will go to 
SecondfM "firing is e nc^- - ic.mg. The first Ilea . ntaining String 
anywhe^" - line rill V- =M firs': :ir.a sent to Secondfii* when this form 

is specified See the source prog-rat flla -1: r .rther information, 

SSENDeS and SRECEIVE.S 

This complementary pair cf programs provides for error-free serial trans- 
mission of any type of files b=;ween Apple II computers at up to 9600 baud and 
up to 600 bau'd for Commodore 64. Files can 3i-:cncr.ged bstween Appies and 
Commodores, too. The programs are cascribec J. The subroutines 

provided can be used as the basis for any ki"i r.f rci^unieetions program. 

TINYTERM.S 

This program is a minimal implementation of a communications program for 
communicating over a modes, tc a time sharing service or bulletin board service. 

It is explained in Appendix 7. 



Revo C 



This page is ir.;er. tionally lafc blanls , 



Copyright (C) 1986 SMA Inc~ R ev . C 



